eurostat-map 4.3.58 → 4.4.1

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
+}

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,71 @@
+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. */
+        nutsrg?: any[]
+        /** Nutsbn. */
+        nutsbn?: any[]
+        /** Cntrg. */
+        cntrg?: any[]
+        /** Cntbn. */
+        cntbn?: any[]
+        /** Worldrg. */
+        worldrg?: any[]
+        /** Graticule. */
+        graticule?: any[]
+        /** Mixed. */
+        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(
+        /** Zoom group. */
+        zoomGroup: any,
+        /** Draw graticule. */
+        drawGraticule: boolean,
+        /** Path function. */
+        pathFunction: any,
+        /** Nuts level. */
+        nutsLevel: number | string,
+        /** Nuts year. */
+        nutsYear: number,
+        /** Geo. */
+        geo: string,
+        /** Proj. */
+        proj: string,
+        /** Scale. */
+        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,12 @@
+/**
+ * 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. */
+        type: 'FeatureCollection'
+        /** Features. */
+        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,113 @@
+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. */
+        label?: string
+        /** Href. */
+        href?: string
+        /** Source. */
+        source?: string
+        /** Updated. */
+        updated?: string
+        /** Time. */
+        time?: string
+        /** Extension. */
+        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
+}