eurostat-map 4.7.0 → 4.8.0

package/build/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eurostat-map",
-  "version": "4.7.0",
+  "version": "4.8.0",
   "description": "Reusable library to quickly create and customise web maps showing Eurostat data directly retrieved from Eurostat database.",
   "keywords": [
     "eurostat",

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

@@ -12,6 +12,7 @@ import type { DorlingSettings } from './DorlingSettings'
 import type { ScalebarConfig } from './decoration/ScalebarConfig'
 import type { EncodingConfig } from './encoding/EncodingConfig'
 import type { LocationConfig } from './locations'
+import type { LabelsConfig } from './decoration/LabelsConfig'
 
 /**
  * A eurostat-map instance. Created by eurostatmap.map() and extended
@@ -257,9 +258,12 @@ export interface MapInstance {
     placenames(): boolean
     placenames(show: boolean): this
 
-    /** Geographic label configuration. See docs/reference.md#labelling */
-    labels(): object | undefined
-    labels(config: object): this
+    /**
+     * Get or set label configuration for country names, statistical values, etc.
+     * @example map.labels({ values: true, backgrounds: true, backgroundFill: '#B19122' })
+     */
+    labels(): LabelsConfig | undefined
+    labels(config: LabelsConfig): this
 
     /** Annotation configuration for d3-svg-annotation. */
     annotations(): any

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

@@ -0,0 +1,89 @@
+/**
+ * Configuration for map labels (country names, statistical values, etc.)
+ */
+export interface LabelsConfig {
+    /**
+     * Array of label objects with text and coordinates.
+     * Use eurostatmap.getDefaultLabels() to get predefined geographic labels.
+     */
+    labels?: Array<{
+        text: string
+        x: number
+        y: number
+        class?: string
+        size?: number
+        rotate?: number
+        letterSpacing?: number
+        cc?: string
+    }>
+
+    /**
+     * Show statistical values as labels on regions.
+     * @default false
+     */
+    values?: boolean
+
+    /**
+     * Apply halo/shadow effect around labels for better readability.
+     * @default false
+     */
+    halos?: boolean
+
+    /**
+     * Legacy alias for halos.
+     * @deprecated Use halos instead
+     */
+    shadows?: boolean
+
+    /**
+     * Apply solid background rectangles behind labels.
+     * Takes precedence over halos when both are set.
+     * @default false
+     */
+    backgrounds?: boolean
+
+    /**
+     * Fill color for label background rectangles (CSS color string).
+     * Only applies when backgrounds is true.
+     * @default '#ffffff'
+     * @example 'white'
+     * @example '#B19122'
+     * @example 'rgba(255, 255, 255, 0.9)'
+     */
+    backgroundFill?: string
+
+    /**
+     * Scale labels when zooming in/out.
+     * @default true
+     */
+    scaleOnZoom?: boolean
+
+    /**
+     * Custom formatter function for statistical value labels.
+     * @example (value) => value.toFixed(1) + '%'
+     */
+    valuesFormatter?: (value: number) => string
+
+    /**
+     * Filter function to show/hide statistical value labels for specific regions.
+     * @param region - GeoJSON feature object
+     * @param map - Map instance
+     * @returns true to show label, false to hide
+     */
+    statLabelsFilterFunction?: (region: any, map: any) => boolean
+
+    /**
+     * Override default centroid positions for statistical value labels.
+     * Keys are region IDs (e.g., 'DE', 'FR01'), values are {x, y} coordinates.
+     */
+    statLabelsPositions?: Record<string, { x: number; y: number }>
+
+    /**
+     * Function to adjust calculated centroids for value labels.
+     * @param region - GeoJSON feature object
+     * @param centroid - Calculated centroid [x, y]
+     * @returns Adjusted centroid [x, y]
+     * @example (region, centroid) => [centroid[0] + 10, centroid[1] - 10]
+     */
+    processValueLabelCentroids?: (region: any, centroid: [number, number]) => [number, number]
+}

package/build/types/legend/choropleth/BivariateLegendConfig.d.ts

@@ -1,138 +1,135 @@
-import { LegendConfig } from '../LegendConfig'
-
-/**
- * Configuration for bivariate choropleth map legends.
- * Displays a 2D grid showing the relationship between two variables,
- * with color squares representing different class combinations.
- */
-export interface BivariateLegendConfig extends LegendConfig {
-    /** Size of the legend square grid in pixels. @default 100 */
-    squareSize?: number
-
-    /** Rotation angle of the legend in degrees. @default 0 */
-    rotation?: number
-
-    /** Label for the first variable (y-axis). @default 'Variable 1' */
-    label1?: string
-
-    /** Label for the second variable (x-axis). @default 'Variable 2' */
-    label2?: string
-
-    /** Break points for the first variable. Auto-calculated if undefined. */
-    breaks1?: number[]
-
-    /** Break points for the second variable. Auto-calculated if undefined. */
-    breaks2?: number[]
-
-    /** Whether to show break labels on the axes. @default false */
-    showBreaks?: boolean
-
-    /** Length of axis tick marks in pixels. @default 5 */
-    tickLength?: number
-
-    /** Offset adjustments for y-axis labels. @default { x: 0, y: 0 } */
-    yAxisLabelsOffset?: { x: number; y: number }
-
-    /** Offset adjustments for x-axis labels. @default { x: 0, y: 0 } */
-    xAxisLabelsOffset?: { x: number; y: number }
-
-    /** Offset adjustments for y-axis title. @default { x: 0, y: 0 } */
-    yAxisTitleOffset?: { x: number; y: number }
-
-    /** Offset adjustments for x-axis title. @default { x: 0, y: 0 } */
-    xAxisTitleOffset?: { x: number; y: number }
-
-    /** Extra vertical offset for the "no data" legend item in pixels. @default 30 */
-    noDataYOffset?: number
-
-    /** Whether to show arrows at the end of the axes. @default true */
-    axisArrows?: boolean
-
-    /** Height of axis arrows in pixels. @default 15 */
-    arrowHeight?: number
-
-    /** Width of axis arrows in pixels. @default 14 */
-    arrowWidth?: number
-
-    /** Padding between arrow and axis label in pixels. @default 10 */
-    arrowPadding?: number
-
-    /**
-     * Labels displayed at low/high ends of each axis.
-     * @default { x: { low: 'Low', high: 'High' }, y: { low: 'Low', high: 'High' } }
-     */
-    axisExtremes?: {
-        x?: { low?: string; high?: string }
-        y?: { low?: string; high?: string }
-    }
-
-    /** Whether to show low/high endpoint labels on both axes. @default true */
-    showAxisExtremes?: boolean
-
-    /**
-     * Optional text annotations for each corner of the bivariate square.
-     * Add text for any combination of topRight, bottomRight, bottomLeft, topLeft.
-     * Supports line breaks using '<br>'/'<br/>' or '\\n'.
-     */
-    annotations?: {
-        topRight?: string
-        bottomRight?: string
-        bottomLeft?: string
-        topLeft?: string
-    }
-
-    /**
-     * Length of corner annotation callout lines in pixels.
-     * Can be a single number for all corners, or per-corner values.
-     * @default 18
-     */
-    annotationLineLength?:
-        | number
-        | {
-              topRight?: number
-              bottomRight?: number
-              bottomLeft?: number
-              topLeft?: number
-          }
-
-    /**
-     * Annotation text offsets in pixels.
-     * Use global `{ x, y }` or per-corner values.
-     * @default auto (based on corner direction)
-     */
-    annotationOffsets?:
-        | { x?: number; y?: number }
-        | {
-              topRight?: { x?: number; y?: number }
-              bottomRight?: { x?: number; y?: number }
-              bottomLeft?: { x?: number; y?: number }
-              topLeft?: { x?: number; y?: number }
-          }
-
-    /**
-     * Extra offset applied to the leader-line endpoint where it meets the annotation label.
-     * Use global `{ x, y }` or per-corner values.
-     * @default { x: 0, y: 0 }
-     */
-    annotationLineEndOffset?:
-        | { x?: number; y?: number }
-        | {
-              topRight?: { x?: number; y?: number }
-              bottomRight?: { x?: number; y?: number }
-              bottomLeft?: { x?: number; y?: number }
-              topLeft?: { x?: number; y?: number }
-          }
-
-    /**
-     * @deprecated Use annotationOffsets instead.
-     * Radial padding between corner annotation callout line end and text in pixels.
-     */
-    annotationPadding?:
-        | number
-        | {
-              topRight?: number
-              bottomRight?: number
-              bottomLeft?: number
-              topLeft?: number
-          }
-}
+import { LegendConfig } from '../LegendConfig'
+
+/**
+ * Configuration for bivariate choropleth map legends.
+ * Displays a 2D grid showing the relationship between two variables,
+ * with color squares representing different class combinations.
+ */
+export interface BivariateLegendConfig extends LegendConfig {
+    /** Size of the legend square grid in pixels. @default 100 */
+    squareSize?: number
+
+    /** Rotation angle of the legend in degrees. @default 0 */
+    rotation?: number
+
+    /** Label for the first variable (y-axis). @default 'Variable 1' */
+    label1?: string
+
+    /** Label for the second variable (x-axis). @default 'Variable 2' */
+    label2?: string
+
+    /** Break labels for the first variable. Omit to hide first-axis break labels. */
+    breaks1?: Array<number | string>
+
+    /** Break labels for the second variable. Omit to hide second-axis break labels. */
+    breaks2?: Array<number | string>
+
+    /** Length of axis tick marks in pixels. @default 5 */
+    tickLength?: number
+
+    /** Offset adjustments for y-axis labels. @default { x: 0, y: 0 } */
+    yAxisLabelsOffset?: { x: number; y: number }
+
+    /** Offset adjustments for x-axis labels. @default { x: 0, y: 0 } */
+    xAxisLabelsOffset?: { x: number; y: number }
+
+    /** Offset adjustments for y-axis title. @default { x: 0, y: 0 } */
+    yAxisTitleOffset?: { x: number; y: number }
+
+    /** Offset adjustments for x-axis title. @default { x: 0, y: 0 } */
+    xAxisTitleOffset?: { x: number; y: number }
+
+    /** Extra vertical offset for the "no data" legend item in pixels. @default 30 */
+    noDataYOffset?: number
+
+    /** Whether to show arrows at the end of the axes. @default true */
+    axisArrows?: boolean
+
+    /** Height of axis arrows in pixels. @default 15 */
+    arrowHeight?: number
+
+    /** Width of axis arrows in pixels. @default 14 */
+    arrowWidth?: number
+
+    /** Padding between arrow and axis label in pixels. @default 10 */
+    arrowPadding?: number
+
+    /**
+     * Labels displayed at low/high ends of each axis.
+     * @default { x: { low: 'Low', high: 'High' }, y: { low: 'Low', high: 'High' } }
+     */
+    axisExtremes?: {
+        x?: { low?: string; high?: string }
+        y?: { low?: string; high?: string }
+    }
+
+    /** Whether to show low/high endpoint labels on both axes. @default true */
+    showAxisExtremes?: boolean
+
+    /**
+     * Optional text annotations for each corner of the bivariate square.
+     * Add text for any combination of topRight, bottomRight, bottomLeft, topLeft.
+     * Supports line breaks using '<br>'/'<br/>' or '\\n'.
+     */
+    annotations?: {
+        topRight?: string
+        bottomRight?: string
+        bottomLeft?: string
+        topLeft?: string
+    }
+
+    /**
+     * Length of corner annotation callout lines in pixels.
+     * Can be a single number for all corners, or per-corner values.
+     * @default 18
+     */
+    annotationLineLength?:
+        | number
+        | {
+              topRight?: number
+              bottomRight?: number
+              bottomLeft?: number
+              topLeft?: number
+          }
+
+    /**
+     * Annotation text offsets in pixels.
+     * Use global `{ x, y }` or per-corner values.
+     * @default auto (based on corner direction)
+     */
+    annotationOffsets?:
+        | { x?: number; y?: number }
+        | {
+              topRight?: { x?: number; y?: number }
+              bottomRight?: { x?: number; y?: number }
+              bottomLeft?: { x?: number; y?: number }
+              topLeft?: { x?: number; y?: number }
+          }
+
+    /**
+     * Extra offset applied to the leader-line endpoint where it meets the annotation label.
+     * Use global `{ x, y }` or per-corner values.
+     * @default { x: 0, y: 0 }
+     */
+    annotationLineEndOffset?:
+        | { x?: number; y?: number }
+        | {
+              topRight?: { x?: number; y?: number }
+              bottomRight?: { x?: number; y?: number }
+              bottomLeft?: { x?: number; y?: number }
+              topLeft?: { x?: number; y?: number }
+          }
+
+    /**
+     * @deprecated Use annotationOffsets instead.
+     * Radial padding between corner annotation callout line end and text in pixels.
+     */
+    annotationPadding?:
+        | number
+        | {
+              topRight?: number
+              bottomRight?: number
+              bottomLeft?: number
+              topLeft?: number
+          }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "eurostat-map",
-    "version": "4.7.0",
+    "version": "4.8.0",
     "description": "Reusable library to quickly create and customise web maps showing Eurostat data directly retrieved from Eurostat database.",
     "keywords": [
         "cartography",