eurostat-map 4.10.9 → 4.10.11

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

@@ -4,13 +4,41 @@ import type { MapInstance as EurostatMap } from './MapInstance'
  * Configuration for tooltips
  */
 export interface TooltipConfig {
+    /** Custom tooltip text/HTML builder, called with the hovered region/symbol datum and the
+     * map instance. @example (region, map) => `<b>${region.properties.na}</b>` */
     textFunction?: (region: any, map: EurostatMap) => string
-    /** Omit regions. */
+
+    /** Region IDs to skip showing/updating the tooltip for. */
     omitRegions?: string[]
-    /** Max width. */
-    maxWidth?: number
-    /** Font size. */
-    fontSize?: number
+
+    /**
+     * Fixed decimal places for the tooltip's displayed value (choropleth maps). Preserves
+     * trailing zeros (e.g. 7 -> "7.0") that the default formatter otherwise drops. Defaults to
+     * the max precision seen across the stat dataset's own values when unset.
+     */
+    decimals?: number
+
+    /** Show status flags (e.g. estimated/provisional) next to the value. Pass 'short' for the
+     * raw flag code instead of the expanded label. @default false */
+    showFlags?: boolean | 'short'
+
+    /** Id of the container element used to constrain the tooltip's position/bounds.
+     * @default the map's containerId, or svgId, or 'map' */
+    containerId?: string
+
+    /** Id of the tooltip's own `<div>` element. @default `em-tooltip-${containerId}` */
+    id?: string
+
+    /** Pixel offset {x, y} of the tooltip from the pointer. Takes precedence over xOffset/yOffset. */
+    offset?: { x?: number; y?: number }
+
+    /** X pixel offset of the tooltip from the pointer, used when offset.x is unset. @default 30 */
+    xOffset?: number
+    /** Y pixel offset of the tooltip from the pointer, used when offset.y is unset. @default 20 */
+    yOffset?: number
+
+    /** Opacity of the tooltip when shown. @default 1 */
+    opacity?: number
 
     [key: string]: any
 }

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

@@ -0,0 +1,34 @@
+/**
+ * Configuration for a single fill pattern overlay applied to specific regions.
+ * Pass an array of these to `map.patternFill([...])` to hatch/dot/cross-hatch specific
+ * regions on top of their normal fill (e.g. to flag missing/estimated data).
+ */
+export interface PatternFillConfig {
+    /** Built-in pattern name, or any string when using a customPattern with a matching id. @default 'hatching' */
+    pattern?: 'hatching' | 'crosshatch' | 'dots' | (string & {})
+
+    /** Region IDs to apply this pattern to. */
+    regionIds?: string[]
+
+    /** Stroke/dot color for the pattern. @default '#000' */
+    color?: string
+
+    /** Stroke width (hatching/crosshatch) or dot radius (dots). @default 1 */
+    strokeWidth?: number
+
+    /** Distance between repeated pattern elements in pixels. @default 8 */
+    spacing?: number
+
+    /**
+     * Raw SVG markup for a custom `<pattern>` element, used instead of a built-in pattern.
+     * Must include an `id` attribute; that id is then used to reference the pattern.
+     * @example '<pattern id="my-pattern" ...>...</pattern>'
+     */
+    customPattern?: string
+
+    /** Label shown for this pattern in the legend. Patterns without a label are omitted from the legend. */
+    legendLabel?: string
+
+    /** Internal: resolved pattern element id, set automatically. */
+    patternId?: string
+}

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

@@ -35,8 +35,16 @@ export interface GeometriesClass {
     /** Master copy of all centroid features before filtering */
     _allCentroidsFeatures: any[]
 
+    /** Returns GeoJSON features for all statistical regions at the map's current NUTS level
+     * (or the 4-level array [rg0,rg1,rg2,rg3] when nutsLevel is 'mixed', or worldrg for WORLD geo). */
+    getRegionFeatures(): any[]
+
     /** Fetches default geographic data from NUTS2JSON */
-    getDefaultGeoData(geo: string, filterFunction: any, nutsLevel: number | string): Promise<void>
+    getDefaultGeoData(geo: string, filterFunction: any, nutsLevel: number | string): Promise<any[]>
+    /** Returns the array of NUTS2JSON fetch promises used by getDefaultGeoData(). */
+    getDefaultGeoDataPromise(): Promise<any>[]
+    /** Returns true once default geo data (or user geometries) has loaded for this map and every inset. */
+    isGeoReady(): boolean
     /** Sets user-defined custom geometries */
     setUserGeometries(geometries: any[]): void
     /** Adds default NUTS geometries to the map */
@@ -60,6 +68,10 @@ export interface GeometriesClass {
     ): void
     /** Adds user-defined geometries to the map */
     addUserGeometriesToMap(geometries: any[], zoomGroup: any, pathFunction: any): void
+    /** Returns all statistical region features (used e.g. for statistical value labelling). */
+    getAllRegionFeatures(): any[]
+    /** Returns a Map of region id -> projected [x, y] centroid, computed via the given d3 path function. */
+    getRegionCentroids(pathFunction: any): Map<string, [number, number]>
 }
 
 /**

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

@@ -1,31 +1,49 @@
-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
-}
+import type { MapInstance } from '../MapInstance'
+import type { EncodingConfig } from '../encoding/EncodingConfig'
+import type { StatData } from '../stat/StatData'
+import type { StatConfig } from '../stat/StatConfig'
+import type { CompositionStatConfig } from '../../layers/composition/CompositionStatConfig'
+import type { LegendConfig } from '../../legend/LegendConfig'
+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
+
+    /** Forwards to the owning map's stat() - statistical data is always map-level. */
+    stat(): StatConfig | CompositionStatConfig | undefined
+    stat(config: StatConfig | CompositionStatConfig): this
+    stat(key: string): StatConfig | CompositionStatConfig | undefined
+    stat(key: string, config: StatConfig | CompositionStatConfig): this
+
+    /** Forwards to the owning map's statData() - statistical data is always map-level. */
+    statData(): StatData
+    statData(key: string): StatData
+    statData(key: string, data: StatData): this
+
+    /** Get or set this layer's own legend configuration, independent of the map facade's. */
+    legend(): LegendConfig | false | undefined
+    legend(config: LegendConfig | false): this
+
+    updateClassification(): Layer
+    updateStyle(): Layer
+    getLegendConstructor(): (map: MapInstance, config?: any) => any
+    group(): any // d3 selection
+}

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

@@ -4,12 +4,20 @@ import type { MapInstance } from './MapInstance'
  * Configuration for the minimap globe feature.
  */
 export interface MinimapConfig {
-    /** Size of the minimap in pixels. @default 150 */
+    /** Diameter of the minimap in pixels. @default 160 (defaults to 150 if unset before first draw) */
     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]
+    /** X position of the minimap center in pixels. @default 80 */
+    x?: number
+    /** Y position of the minimap center in pixels. @default 80 */
+    y?: number
+    /** Orthographic projection scale (globe zoom level) in pixels. @default 160 */
+    z?: number
+    /** Color of the outer ring and highlighted region(s). @default '#929292ff' */
+    color?: string
+    /** Region/country IDs to highlight on the globe (e.g. the main map's current country focus). */
+    highlightIds?: string[]
 }
 
 /**

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

@@ -1,5 +1,3 @@
-import type { StatConfig } from './StatConfig'
-
 /**
  * A statistical dataset indexed by NUTS region ID.
  * Returned by map.statData() and created internally by statData().
@@ -101,6 +99,8 @@ export interface StatData {
     eurostatDatasetCode_?: string
     /** CSV source URL. */
     csvURL_?: string
+    /** Dataset label/name from the Eurostat API response or stat() config. */
+    label_?: string
 
     /**
      * Fetches data from the configured remote source (Eurostat API or CSV).

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

@@ -196,3 +196,47 @@ export const compactFormatter: Intl.NumberFormat
  * Long number formatter.
  */
 export const longFormatter: Intl.NumberFormat
+
+/**
+ * Formats a raw numeric value as a space-thousands-separated string (e.g. 1234567 -> "1 234 567").
+ * Returns '0' for null/undefined/NaN input.
+ */
+export function formatRawValue(value: number | null | undefined): string
+
+/**
+ * Prefix used to encode extra categorical values (e.g. "no data" exceptions) mixed into an
+ * otherwise-numeric choropleth classification, so they don't collide with numeric class indices.
+ */
+export const CATEGORY_ECL_PREFIX: string
+
+/**
+ * Encodes a raw categorical value as an `ecl` attribute value, prefixed with CATEGORY_ECL_PREFIX.
+ */
+export function toCategoryEcl(rawValue: string | number): string
+
+/**
+ * Decodes an `ecl` attribute value produced by toCategoryEcl() back to its raw categorical value.
+ * Returns undefined if the input isn't a category-prefixed ecl value.
+ */
+export function fromCategoryEcl(ecl: string): string | undefined
+
+/**
+ * Rounds a value to the nearest "nice" number (1, 1.5, 2, 2.5, 3, 4, 5, 6, 7, 8, 9, or 10 times a
+ * power of ten), clamped to the given [min, max] range (with a small margin).
+ */
+export function roundToNiceNumber(value: number, min: number, max: number): number
+
+/**
+ * Adjusts a sorted array of unique threshold values to have exactly targetCount entries, splitting
+ * the largest gap (including the gaps to min/max) when rounding produced duplicates/fewer values
+ * than requested.
+ */
+export function adjustDuplicateThresholds(uniqueThresholds: number[], targetCount: number, min: number, max: number): number[]
+
+/**
+ * Rounds classification thresholds to nice, legible values while preserving the original
+ * threshold count, resolving any duplicates introduced by rounding.
+ * @param thresholds - Raw threshold values from the classifier
+ * @param values - Full data array (used to derive min/max bounds)
+ */
+export function applyNiceNumbers(thresholds: number[], values: number[]): number[]

package/build/types/index.d.ts

@@ -65,6 +65,7 @@ export type { CoastalMarginSettings } from './core/decoration/CoastalMarginSetti
 export type { ScalebarConfig } from './core/decoration/ScalebarConfig'
 export type { StampConfig } from './core/decoration/StampConfig'
 export type { LabelsConfig, Label } from './core/decoration/LabelsConfig'
+export type { PatternFillConfig } from './core/decoration/PatternFillConfig'
 export type { RankedBarChartConfig } from './core/decoration/RankedBarChartConfig'
 export type { GridCartogramSettings, GridCartogramMargins } from './core/GridCartogramSettings'
 export type { DorlingSettings, DorlingStrength } from './core/DorlingSettings'
@@ -75,6 +76,8 @@ export type { Layer } from './core/layer/Layer'
 export type { LayerConfig } from './core/layer/LayerConfig'
 export type { LayerRole } from './core/layer/LayerRole'
 
+import type { LayerRole } from './core/layer/LayerRole'
+
 // ==================== Legend Configuration Type Exports ====================
 
 // Main legend types
@@ -91,14 +94,14 @@ export type { TrivariateLegendConfig } from './legend/choropleth/TrivariateLegen
 
 // Composition legend types
 export type { BarChartLegendConfig } from './legend/composition/BarChartLegendConfig'
-export type { BarChartSizeLegendConfig, BarChartColorLegendConfig } from './legend/composition/BarChartLegendConfig'
+export type { BarChartSizeLegendConfig, BarChartWidthLegendConfig, BarChartColorLegendConfig } from './legend/composition/BarChartLegendConfig'
 export type { CoxcombLegendConfig } from './legend/composition/CoxcombLegendConfig'
 export type { CoxcombSizeLegendConfig, CoxcombColorLegendConfig, CoxcombTimeLegendConfig } from './legend/composition/CoxcombLegendConfig'
 export type { PieChartLegendConfig } from './legend/composition/PieChartLegendConfig'
 export type { PieChartSizeLegendConfig, PieChartColorLegendConfig } from './legend/composition/PieChartLegendConfig'
 export type { WaffleLegendConfig } from './legend/composition/WaffleLegendConfig'
 export type { WaffleSizeLegendConfig, WaffleColorLegendConfig } from './legend/composition/WaffleLegendConfig'
-export type { StripeCompositionLegendConfig } from './legend/composition/StripeCompositionLegendConfig'
+export type { StripeCompositionLegendConfig, StripeCompositionColorLegendConfig } from './legend/composition/StripeCompositionLegendConfig'
 export type {
     SparklineLegendConfig,
     SparklineScaleLegendConfig,
@@ -235,20 +238,42 @@ export function map(type: MapType, config?: MapConfig): MapInstance
  */
 export function getFillPatternDefinitionFunction(opts?: FillPatternOptions): (svg: any, numberOfClasses: number) => void
 
+/**
+ * @deprecated Use getFillPatternDefinitionFunction instead. Kept as an alias for backwards
+ * compatibility.
+ */
+export function getFillPatternDefinitionFun(opts?: FillPatternOptions): (svg: any, numberOfClasses: number) => void
+
 /**
  * Get default labels for the map
  */
 export function getDefaultLabels(): { [key: string]: any }
 
+/**
+ * Registers a custom layer type so it can be used with map.addLayer() and, once the type
+ * itself is recognized elsewhere in the build chain, with eurostatmap.map(type).
+ *
+ * @param type - Unique layer type identifier
+ * @param role - 'base' (paints shared region geometry, at most one per map) or 'overlay'
+ * @param decorate - Function that attaches the layer's fluent API/behavior onto a created Layer
+ */
+export function registerLayerType(type: string, role: LayerRole, decorate: (layer: any, config: any) => void): void
+
+/**
+ * Returns true if the given layer type has been registered via registerLayerType (or is a
+ * built-in type available through the multi-layer API).
+ */
+export function isLayerTypeRegistered(type: string): boolean
+
 /**
  * Project coordinates from map pixel space to geographic coordinates
  *
  * @param map - The map object
  * @param x - X pixel coordinate
  * @param y - Y pixel coordinate
- * @returns [longitude, latitude]
+ * @returns [longitude, latitude], or null if projection fails
  */
-export function projectFromMap(map: MapInstance, x: number, y: number): [number, number]
+export function projectFromMap(map: MapInstance, x: number, y: number): [number, number] | null
 
 /**
  * Project geographic coordinates to map pixel space
@@ -256,9 +281,9 @@ export function projectFromMap(map: MapInstance, x: number, y: number): [number,
  * @param map - The map object
  * @param lon - Longitude
  * @param lat - Latitude
- * @returns [x, y] pixel coordinates
+ * @returns [x, y] pixel coordinates, or null if projection fails
  */
-export function projectToMap(map: MapInstance, lon: number, lat: number): [number, number]
+export function projectToMap(map: MapInstance, lon: number, lat: number): [number, number] | null
 
 /**
  * Library version
@@ -272,12 +297,18 @@ declare const eurostatmap: {
     map: typeof map
     /** Get fill pattern definition function. */
     getFillPatternDefinitionFunction: typeof getFillPatternDefinitionFunction
+    /** @deprecated Use getFillPatternDefinitionFunction instead. */
+    getFillPatternDefinitionFun: typeof getFillPatternDefinitionFun
     /** Get default labels. */
     getDefaultLabels: typeof getDefaultLabels
     /** Project from map. */
     projectFromMap: typeof projectFromMap
     /** Project to map. */
     projectToMap: typeof projectToMap
+    /** Register a custom layer type. */
+    registerLayerType: typeof registerLayerType
+    /** Check whether a layer type is registered. */
+    isLayerTypeRegistered: typeof isLayerTypeRegistered
     /** Version. */
     version: typeof version
 }

package/build/types/layers/CategoricalMap.d.ts

@@ -4,18 +4,18 @@ import type { MapInstance } from '../core/MapInstance'
  * Categorical map type.
  */
 export interface CategoricalMap extends MapInstance {
-    classToFillStyle(): any
-    classToFillStyle(v: any): this
+    /** Fill color for each category value. Auto-generated from a default palette when unset. */
+    classToFillStyle(): Record<string, string> | undefined
+    classToFillStyle(v: Record<string, string>): this
 
-    classToText(): any
-    classToText(v: any): this
+    /** Legend/tooltip label for each category value. */
+    classToText(): Record<string, string> | undefined
+    classToText(v: Record<string, string>): this
 
     noDataFillStyle(): string
     noDataFillStyle(v: string): this
 
-    tooltipText(): any
-    tooltipText(v: any): this
-
-    classifier(): any
-    classifier(v: any): this
+    /** The classifier (d3 ordinal scale) mapping a category value to a class number. */
+    classifier(): ((value: string | number) => number) & { domain: (d?: (string | number)[]) => any }
+    classifier(v: ((value: string | number) => number) & { domain?: (d?: (string | number)[]) => any }): this
 }

package/build/types/layers/choropleth/BivariateChoroplethConfig.d.ts

@@ -22,6 +22,9 @@ export interface BivariateChoroplethConfig extends MapConfig {
     color2?: string
     /** End color. */
     endColor?: string
+    /** Function mapping the two class indices (ecl1, ecl2) to a fill color. Auto-derived from
+     * startColor/color1/color2/endColor (or the legacy oranges/blues default) when unset. */
+    classToFillStyle?: (ecl1: number, ecl2: number) => string | null
     /** No data fill style. */
     noDataFillStyle?: string
 }

package/build/types/layers/choropleth/BivariateChoroplethMap.d.ts

@@ -25,15 +25,18 @@ export interface BivariateChoroplethMap extends MapInstance {
     endColor(): string
     endColor(v: string): this
 
-    classToFillStyle(): any
-    classToFillStyle(v: any): this
+    /** Function mapping the two class indices (ecl1, ecl2) to a fill color. */
+    classToFillStyle(): (ecl1: number, ecl2: number) => string | null
+    classToFillStyle(v: (ecl1: number, ecl2: number) => string | null): this
 
     noDataFillStyle(): string
     noDataFillStyle(v: string): this
 
-    classifier1(): any
-    classifier1(v: any): this
+    /** The classifier (d3 scale) mapping the first variable's stat value to a class number. */
+    classifier1(): ((value: number) => number) | undefined
+    classifier1(v: (value: number) => number): this
 
-    classifier2(): any
-    classifier2(v: any): this
+    /** The classifier (d3 scale) mapping the second variable's stat value to a class number. */
+    classifier2(): ((value: number) => number) | undefined
+    classifier2(v: (value: number) => number): this
 }

package/build/types/layers/choropleth/ChoroplethConfig.d.ts

@@ -22,8 +22,8 @@ export interface ChoroplethConfig extends MapConfig {
     colorFunction?: (t: number) => string
     /** Color scheme type. */
     colorSchemeType?: 'discrete' | 'continuous'
-    /** Class to fill style. */
-    classToFillStyle?: { [classIndex: number]: string }
+    /** Function mapping a class index (or category ecl code) and the number of classes to a fill color. */
+    classToFillStyle?: (ecl: number | string, numberOfClasses: number) => string
 
     /** No-data styling. */
     noDataFillStyle?: string
@@ -44,5 +44,5 @@ export interface ChoroplethConfig extends MapConfig {
     skipNormalization?: boolean
 
     /** Diverging schemes. */
-    pointOfDivergence?: number
+    pointOfDivergence?: number | null
 }

package/build/types/layers/choropleth/ChoroplethMap.d.ts

@@ -22,11 +22,13 @@ export interface ChoroplethMap extends MapInstance {
     makeClassifNice(): boolean
     makeClassifNice(v: boolean): this
 
-    classToFillStyle(): any
-    classToFillStyle(v: any): this
+    /** Function mapping a class index (or category ecl code) and the number of classes to a fill color. */
+    classToFillStyle(): (ecl: number | string, numberOfClasses: number) => string
+    classToFillStyle(v: (ecl: number | string, numberOfClasses: number) => string): this
 
-    classifier(): any
-    classifier(v: any): this
+    /** The classifier function/scale mapping a stat value to a class number. */
+    classifier(): (value: number) => number
+    classifier(v: (value: number) => number): this
 
     colorSchemeType(): string
     colorSchemeType(type: 'discrete' | 'continuous'): this
@@ -51,4 +53,14 @@ export interface ChoroplethMap extends MapInstance {
 
     categoryText(): { [rawValue: string]: string } | undefined
     categoryText(v: { [rawValue: string]: string }): this
+
+    /** SVG filter/pattern definition function used for fill patterns (e.g. dot density). */
+    filtersDefinitionFunction(): ((svg: any, numberOfClasses: number) => void) | undefined
+    filtersDefinitionFunction(fn: (svg: any, numberOfClasses: number) => void): this
+
+    /** Manually highlight a region by ID, simulating a mouseover (fill + tooltip). */
+    highlightRegion(regionId: string): this
+
+    /** Clear any region highlighted via highlightRegion(), simulating a mouseout. */
+    clearHighlight(): this
 }

package/build/types/layers/choropleth/TrivariateChoroplethMap.d.ts

@@ -7,6 +7,10 @@ type TernarySettings = TrivariateTernarySettings
  * Trivariate choropleth map type.
  */
 export interface TrivariateChoroplethMap extends MapInstance {
+    /** Returns the resolved [v1, v2, v3] stat codes for the three ternary variables, honoring
+     * any 'color' encoding before falling back to ternaryCodes. */
+    getTernaryStatCodes(): [string, string, string]
+
     ternaryCodes(): string[]
     ternaryCodes(v: string[]): this
 

package/build/types/layers/choropleth/ValueByAlphaMap.d.ts

@@ -1,9 +1,10 @@
-import type { MapInstance } from '../../core/MapInstance'
+import type { ChoroplethMap } from './ChoroplethMap'
 
 /**
- * Value-by-alpha choropleth map type.
+ * Value-by-alpha choropleth map type. Extends the choropleth map API (it reuses
+ * decorateChoroplethLayer internally) with an opacity channel driven by a second stat.
  */
-export interface ValueByAlphaMap extends MapInstance {
+export interface ValueByAlphaMap extends ChoroplethMap {
     opacityScale(): ((value: number) => number) | null
     opacityScale(v: ((value: number) => number) | null): this
 }