eurostat-map 4.4.4 → 4.5.0

package/build/types/layers/spark/SparkMap.d.ts

@@ -0,0 +1,56 @@
+import type { MapInstance } from '../../core/MapInstance'
+import type { SparkStatConfig } from './SparkStatConfig'
+import type { SparklineLegendConfig } from '../../legend/composition/SparklineLegendConfig'
+import type { SparkSettings } from './SparkMapConfig'
+
+/**
+ * Spark map type.
+ */
+export interface SparkMap extends MapInstance {
+    sparkSettings(): SparkSettings
+    sparkSettings(v: SparkSettings): this
+
+    legend(): SparklineLegendConfig | false
+    legend(config: SparklineLegendConfig | false): this
+
+    sparkLineColor(): any
+    sparkLineColor(v: any): this
+
+    showOnlyWhenComplete(): boolean
+    showOnlyWhenComplete(v: boolean): this
+
+    sparkType(): 'line' | 'area' | 'bar'
+    sparkType(v: 'line' | 'area' | 'bar'): this
+
+    sparkLineWidth(): number
+    sparkLineWidth(v: number): this
+
+    sparkLineHeight(): number
+    sparkLineHeight(v: number): this
+
+    sparkLineStrokeWidth(): number
+    sparkLineStrokeWidth(v: number): this
+
+    sparkLineOpacity(): number
+    sparkLineOpacity(v: number): this
+
+    sparkLineCircleRadius(): number
+    sparkLineCircleRadius(v: number): this
+
+    sparkLineAreaColor(): any
+    sparkLineAreaColor(v: any): this
+
+    sparkTooltipChart(): any
+    sparkTooltipChart(v: any): this
+
+    sparkLineChartFunction(): any
+    sparkLineChartFunction(v: any): this
+
+    sparkLineOffsets(): { x: number; y: number }
+    sparkLineOffsets(v: { x: number; y: number }): this
+
+    /** Manually set sparkline data instead of fetching it from Eurostat. */
+    sparklineData(dataObject: Record<string, Record<string, number>>): this
+    /** Configure fetching data from Eurostat and generating spark lines. */
+    statSpark(config: SparkStatConfig): this
+}

package/build/types/layers/spark/SparkMapConfig.d.ts

@@ -0,0 +1,75 @@
+import type { MapConfig } from '../../core/MapConfig'
+import type { SparklineLegendConfig } from '../../legend/composition/SparklineLegendConfig'
+
+export interface SparkSettings {
+    type?: 'line' | 'area' | 'bar'
+    lineOffsets?: { x: number; y: number }
+    lineWidth?: number
+    lineHeight?: number
+    lineStrokeWidth?: number
+    lineOpacity?: number
+    lineColor?: string | ((value: number, index: number, data: any[]) => string)
+    areaColor?: string | ((value: number, index: number, data: any[]) => string)
+    lineCircleRadius?: number
+    tooltipChart?: {
+        width: number
+        height: number
+        margin: { left: number; right: number; top: number; bottom: number }
+        circleRadius: number
+    }
+    lineChartFunction?: (node: any, data: any[], width: number, height: number, isForTooltip?: boolean) => void
+}
+
+/**
+ * Configuration for sparkline maps.
+ */
+export interface SparkMapConfig extends MapConfig {
+    /** Grouped sparkline rendering settings. */
+    sparkSettings?: SparkSettings
+
+    /** Spark type. */
+    sparkType?: 'line' | 'area' | 'bar'
+
+    /** Object-form stat configuration for temporal sparkline datasets. */
+    dates?: string[]
+    labels?: string[]
+    eurostatDatasetCode?: string
+    customData?: Record<string, Record<string, number>>
+    filters?: Record<string, any>
+    unitText?: string
+    preprocess?: (regionId: string, value: any) => any
+    transform?: (value: any) => any
+
+    sparkLineColor?: string | ((value: number, index: number, data: any[]) => string)
+    sparkAreaColor?: string | ((value: number, index: number, data: any[]) => string)
+    /** Spark line width. */
+    sparkLineWidth?: number
+    /** Spark line height. */
+    sparkLineHeight?: number
+    /** Spark line stroke width. */
+    sparkLineStrokeWidth?: number
+    /** Spark line opacity. */
+    sparkLineOpacity?: number
+    /** Spark line circle radius. */
+    sparkLineCircleRadius?: number
+    /** Spark tooltip chart. */
+    sparkTooltipChart?: {
+        /** Width. */
+        width: number
+        /** Height. */
+        height: number
+        /** Margin. */
+        margin: { left: number; right: number; top: number; bottom: number }
+        /** Circle radius. */
+        circleRadius: number
+    }
+    /** Spark line offsets. */
+    sparkLineOffsets?: { x: number; y: number }
+    /** Show only when complete. */
+    showOnlyWhenComplete?: boolean
+    sparkLineChartFunction?: (node: any, data: any[], width: number, height: number, isForTooltip?: boolean) => void
+    /** Spark yscale. */
+    sparkYScale?: any
+    /** Legend. */
+    legend?: SparklineLegendConfig | false
+}

package/build/types/layers/spark/SparkStatConfig.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Statistical configuration for sparkline maps.
+ *
+ * Either `eurostatDatasetCode` + `dates` (Eurostat API path)
+ * or `customData` (custom data path) must be provided.
+ */
+export interface SparkStatConfig {
+    /**
+     * Custom data keyed by region ID then date string.
+     * Use instead of `eurostatDatasetCode` when supplying data directly.
+     * When `customData` is set, `eurostatDatasetCode` is not required;
+     * `dates` defaults to the key order of the first region's entries.
+     * @example
+     * customData: {
+     *   ES: { '2020': 100, '2021': 120, '2022': 115 },
+     *   DE: { '2020': 200, '2021': 190, '2022': 210 },
+     * }
+     */
+    customData?: Record<string, Record<string, number>>
+
+    /** Eurostat dataset code. Required when not using `customData`. */
+    eurostatDatasetCode?: string
+    /** Filters. */
+    filters?: Record<string, any>
+    /** Unit text. */
+    unitText?: string
+    preprocess?: (regionId: string, value: any) => any
+    transform?: (value: number) => number
+    /** Date keys to fetch. Required when not using `customData`. */
+    dates?: string[]
+    /** Display labels for each date. */
+    labels?: string[]
+}

package/build/types/legend/LegendConfig.d.ts

@@ -6,6 +6,8 @@ export interface LegendConfig {
     x?: number
     /** Legend origin y-coordinate in pixels. */
     y?: number
+    /** Automatically position the legend in a map corner. Manual x/y coordinates take precedence. */
+    position?: 'top right' | 'bottom right' | 'top left' | 'bottom left'
     /** Legend width in pixels. */
     width?: number
     /** Legend height in pixels. */
@@ -65,4 +67,5 @@ export interface LegendConfig {
     maxMin?: boolean
     /** Text affixes for min/max labels as [minSuffix, maxSuffix]. */
     maxMinLabels?: [string, string]
+    layer?: any
 }

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

@@ -56,4 +56,83 @@ export interface BivariateLegendConfig extends LegendConfig {
 
     /** 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/build/types/map-types/choropleth/TrivariateChoroplethConfig.d.ts

@@ -1,6 +1,30 @@
 import type { MapConfig } from '../../core/MapConfig'
 import type { TrivariateLegendConfig } from '../../legend/choropleth/TrivariateLegendConfig'
 
+/**
+ * Ternary color settings for trivariate choropleth maps.
+ */
+export interface TrivariateTernarySettings {
+    /** Use sextant color mapping instead of continuous tricolore. */
+    sextant?: boolean
+    /** Array of 6 colors used when sextant mode is enabled. */
+    sextantColors?: [string, string, string, string, string, string]
+    /** Hue. */
+    hue?: number
+    /** Chroma. */
+    chroma?: number
+    /** Lightness. */
+    lightness?: number
+    /** Contrast. */
+    contrast?: number
+    /** Spread. */
+    spread?: number
+    /** Breaks. */
+    breaks?: number
+    /** Mean centering. */
+    meanCentering?: boolean
+}
+
 /**
  * Configuration for trivariate choropleth maps.
  */
@@ -13,20 +37,5 @@ export interface TrivariateChoroplethConfig extends MapConfig {
     /** No data fill style. */
     noDataFillStyle?: string
     /** Ternary settings. */
-    ternarySettings?: {
-        /** Hue. */
-        hue?: number
-        /** Chroma. */
-        chroma?: number
-        /** Lightness. */
-        lightness?: number
-        /** Contrast. */
-        contrast?: number
-        /** Spread. */
-        spread?: number
-        /** Breaks. */
-        breaks?: number
-        /** Mean centering. */
-        meanCentering?: boolean
-    }
+    ternarySettings?: TrivariateTernarySettings
 }

package/build/types/map-types/choropleth/TrivariateChoroplethMap.d.ts

@@ -1,4 +1,7 @@
 import type { MapInstance } from '../../core/MapInstance'
+import type { TrivariateChoroplethConfig, TrivariateTernarySettings } from './TrivariateChoroplethConfig'
+
+type TernarySettings = TrivariateTernarySettings
 
 /**
  * Trivariate choropleth map type.
@@ -10,6 +13,6 @@ export interface TrivariateChoroplethMap extends MapInstance {
     noDataFillStyle(): string
     noDataFillStyle(v: string): this
 
-    ternarySettings(): any
-    ternarySettings(v: any): this
+    ternarySettings(): TernarySettings
+    ternarySettings(v: Partial<TernarySettings>): this
 }

package/build/types/map-types/composition/CompositionStatConfig.d.ts

@@ -1,8 +1,15 @@
 /**
  * Statistical configuration for composition maps (pie, bar, waffle, stripe).
  *
+ * Preferred API:
+ * - `map.stat('composition', { ... })`
+ * - `map.encoding('composition', { stat: 'composition' })`
+ *
  * Either `eurostatDatasetCode` + `categoryParameter` (Eurostat API path)
  * or `customData` (custom data path) must be provided.
+ *
+ * Legacy positional signatures in `statPie/statWaffle/statBar/statStripe` and
+ * `map.stat('composition', config, categoryParameter, ...)` remain supported.
  */
 export interface CompositionStatConfig<TCustomData = Record<string, Record<string, number>>> {
     /**

package/build/types/map-types/composition/bar/BarMap.d.ts

@@ -1,79 +1,97 @@
-import type { MapInstance } from '../../../core/MapInstance'
-import type { CompositionStatConfig } from '../CompositionStatConfig'
-import type { BarChartLegendConfig } from '../../../legend/composition/BarChartLegendConfig'
-
-/**
- * Bar map type.
- */
-export interface BarMap extends MapInstance {
-    legend(): BarChartLegendConfig | false
-    legend(config: BarChartLegendConfig | false): this
-
-    barType(): 'stacked' | 'grouped'
-    barType(v: 'stacked' | 'grouped'): this
-
-    catColors(): any
-    catColors(v: any): this
-
-    catLabels(): any
-    catLabels(v: any): this
-
-    showOnlyWhenComplete(): boolean
-    showOnlyWhenComplete(v: boolean): this
-
-    noDataFillStyle(): string
-    noDataFillStyle(v: string): this
-
-    barMaxWidth(): number
-    barMaxWidth(v: number): this
-
-    barMinWidth(): number
-    barMinWidth(v: number): this
-
-    barHeight(): number
-    barHeight(v: number): this
-
-    barGroupWidth(): number
-    barGroupWidth(v: number): this
-
-    barGroupGap(): number
-    barGroupGap(v: number): this
-
-    barGroupMinHeight(): number
-    barGroupMinHeight(v: number): this
-
-    barGroupMaxHeight(): number
-    barGroupMaxHeight(v: number): this
-
-    barStrokeFill(): string
-    barStrokeFill(v: string): this
-
-    barStrokeWidth(): number
-    barStrokeWidth(v: number): this
-
-    barCornerRadius(): number
-    barCornerRadius(v: number): this
-
-    barOtherColor(): string
-    barOtherColor(v: string): this
-
-    barOtherText(): string
-    barOtherText(v: string): this
-
-    barTooltipWidth(): number
-    barTooltipWidth(v: number): this
-
-    barTooltipHeight(): number
-    barTooltipHeight(v: number): this
-
-    dorling(): boolean
-    dorling(v: boolean): this
-
-    barTotalCode(): string | undefined
-    barTotalCode(v: string | undefined): this
-
-    statCodes(): string[] | undefined
-    statCodes(v: string[] | undefined): this
-
-    statBar(config: CompositionStatConfig): this
-}
+import type { MapInstance } from '../../../core/MapInstance'
+import type { CompositionStatConfig } from '../CompositionStatConfig'
+import type { BarChartLegendConfig } from '../../../legend/composition/BarChartLegendConfig'
+
+/**
+ * Bar map type.
+ */
+export interface BarMap extends MapInstance {
+    legend(): BarChartLegendConfig | false
+    legend(config: BarChartLegendConfig | false): this
+
+    barType(): 'stacked' | 'grouped'
+    barType(v: 'stacked' | 'grouped'): this
+
+    catColors(): any
+    catColors(v: any): this
+
+    catLabels(): any
+    catLabels(v: any): this
+
+    showOnlyWhenComplete(): boolean
+    showOnlyWhenComplete(v: boolean): this
+
+    noDataFillStyle(): string
+    noDataFillStyle(v: string): this
+
+    barMaxWidth(): number
+    barMaxWidth(v: number): this
+
+    barMinWidth(): number
+    barMinWidth(v: number): this
+
+    barHeight(): number
+    barHeight(v: number): this
+
+    barGroupWidth(): number
+    barGroupWidth(v: number): this
+
+    barSettings(): any
+    barSettings(v: any): this
+
+    barGroupGap(): number
+    barGroupGap(v: number): this
+
+    barGroupMinHeight(): number
+    barGroupMinHeight(v: number): this
+
+    barGroupMaxHeight(): number
+    barGroupMaxHeight(v: number): this
+
+    barStrokeFill(): string
+    barStrokeFill(v: string): this
+
+    barStrokeWidth(): number
+    barStrokeWidth(v: number): this
+
+    barCornerRadius(): number
+    barCornerRadius(v: number): this
+
+    barOtherColor(): string
+    barOtherColor(v: string): this
+
+    barOtherText(): string
+    barOtherText(v: string): this
+
+    barTooltipWidth(): number
+    barTooltipWidth(v: number): this
+
+    barTooltipHeight(): number
+    barTooltipHeight(v: number): this
+
+    dorling(): boolean
+    dorling(v: boolean): this
+
+    barTotalCode(): string | undefined
+    barTotalCode(v: string | undefined): this
+
+    statCodes(): string[] | undefined
+    statCodes(v: string[] | undefined): this
+
+    statBar(config: CompositionStatConfig): this
+    /** @deprecated Legacy positional signature. Prefer statBar({ categoryParameter, categoryCodes, ... }). */
+    statBar(
+        /** Config. */
+        config: CompositionStatConfig,
+        /** Category parameter. */
+        categoryParameter?: string,
+        /** Category codes. */
+        categoryCodes?: string[],
+        /** Category labels. */
+        categoryLabels?: string[],
+        /** Category colors. */
+        categoryColors?: string[],
+        /** Total code. */
+        totalCode?: string
+    ): this
+}

package/build/types/map-types/composition/bar/BarMapConfig.d.ts

@@ -1,54 +1,76 @@
-import type { MapConfig } from '../../../core/MapConfig'
-import type { BarChartLegendConfig } from '../../../legend/composition/BarChartLegendConfig'
-
-/**
- * Configuration for bar chart composition maps.
- */
-export interface BarMapConfig extends MapConfig {
-    /** Bar type. */
-    barType?: 'stacked' | 'grouped'
-    /** Cat colors. */
-    catColors?: Record<string, string>
-    /** Cat labels. */
-    catLabels?: Record<string, string>
-    /** Show only when complete. */
-    showOnlyWhenComplete?: boolean
-    /** No data fill style. */
-    noDataFillStyle?: string
-    /** Bar min width. */
-    barMinWidth?: number
-    /** Bar max width. */
-    barMaxWidth?: number
-    /** Bar height. */
-    barHeight?: number
-    /** Bar group width. */
-    barGroupWidth?: number
-    /** Bar group gap. */
-    barGroupGap?: number
-    /** Bar group min height. */
-    barGroupMinHeight?: number
-    /** Bar group max height. */
-    barGroupMaxHeight?: number
-    /** Bar stroke fill. */
-    barStrokeFill?: string
-    /** Bar stroke width. */
-    barStrokeWidth?: number
-    /** Bar corner radius. */
-    barCornerRadius?: number
-    /** Bar other color. */
-    barOtherColor?: string
-    /** Bar other text. */
-    barOtherText?: string
-    /** Bar tooltip width. */
-    barTooltipWidth?: number
-    /** Bar tooltip height. */
-    barTooltipHeight?: number
-    /** Dorling. */
-    dorling?: boolean
-    /** Bar total code. */
-    barTotalCode?: string
-    /** Stat codes. */
-    statCodes?: string[]
-    /** Legend. */
-    legend?: BarChartLegendConfig | false
-}
+import type { MapConfig } from '../../../core/MapConfig'
+import type { BarChartLegendConfig } from '../../../legend/composition/BarChartLegendConfig'
+
+/**
+ * Configuration for bar chart composition maps.
+ */
+export interface BarMapConfig extends MapConfig {
+    /** Bar type. */
+    barType?: 'stacked' | 'grouped'
+    /** Cat colors. */
+    catColors?: Record<string, string>
+    /** Cat labels. */
+    catLabels?: Record<string, string>
+    /** Show only when complete. */
+    showOnlyWhenComplete?: boolean
+    /** No data fill style. */
+    noDataFillStyle?: string
+    /** Bar min width. */
+    barMinWidth?: number
+    /** Bar max width. */
+    barMaxWidth?: number
+    /** Bar height. */
+    barHeight?: number
+    /** Bar group width. */
+    barGroupWidth?: number
+    /** Grouped bar settings object. */
+    barSettings?: {
+        type?: 'stacked' | 'grouped'
+        minWidth?: number
+        maxWidth?: number
+        height?: number
+        groupWidth?: number
+        groupMinWidth?: number
+        groupMaxWidth?: number
+        groupGap?: number
+        groupMinHeight?: number
+        groupMaxHeight?: number
+        groupMaxValue?: number
+        groupMaxWidthValue?: number
+        strokeFill?: string
+        strokeWidth?: number
+        cornerRadius?: number
+        otherColor?: string
+        otherText?: string
+        tooltipWidth?: number
+        tooltipHeight?: number
+    }
+    /** Bar group gap. */
+    barGroupGap?: number
+    /** Bar group min height. */
+    barGroupMinHeight?: number
+    /** Bar group max height. */
+    barGroupMaxHeight?: number
+    /** Bar stroke fill. */
+    barStrokeFill?: string
+    /** Bar stroke width. */
+    barStrokeWidth?: number
+    /** Bar corner radius. */
+    barCornerRadius?: number
+    /** Bar other color. */
+    barOtherColor?: string
+    /** Bar other text. */
+    barOtherText?: string
+    /** Bar tooltip width. */
+    barTooltipWidth?: number
+    /** Bar tooltip height. */
+    barTooltipHeight?: number
+    /** Dorling. */
+    dorling?: boolean
+    /** Bar total code. */
+    barTotalCode?: string
+    /** Stat codes. */
+    statCodes?: string[]
+    /** Legend. */
+    legend?: BarChartLegendConfig | false
+}