eurostat-map 4.3.58 → 4.4.0

package/build/types/index.d.ts

@@ -0,0 +1,237 @@
+/**
+ * TypeScript definitions for eurostat-map
+ */
+
+// ==================== Core Type Imports (needed for local use in function signatures) ====================
+
+import type { MapConfig } from './core/MapConfig'
+import type { MapType } from './map-types/MapType'
+import type { MapInstance } from './core/MapInstance'
+
+// Choropleth map types
+import type { ChoroplethConfig } from './map-types/choropleth/ChoroplethConfig'
+import type { ChoroplethMap } from './map-types/choropleth/ChoroplethMap'
+import type { ValueByAlphaConfig } from './map-types/choropleth/ValueByAlphaConfig'
+import type { ValueByAlphaMap } from './map-types/choropleth/ValueByAlphaMap'
+import type { BivariateChoroplethConfig } from './map-types/choropleth/BivariateChoroplethConfig'
+import type { BivariateChoroplethMap } from './map-types/choropleth/BivariateChoroplethMap'
+import type { TrivariateChoroplethConfig } from './map-types/choropleth/TrivariateChoroplethConfig'
+import type { TrivariateChoroplethMap } from './map-types/choropleth/TrivariateChoroplethMap'
+
+// Categorical map types
+import type { CategoricalMapConfig } from './map-types/CategoricalMapConfig'
+import type { CategoricalMap } from './map-types/CategoricalMap'
+
+// Proportional symbol map types
+import type { ProportionalSymbolConfig } from './map-types/proportional-symbol/ProportionalSymbolConfig'
+import type { ProportionalSymbolMap } from './map-types/proportional-symbol/ProportionalSymbolMap'
+import type { MushroomMapConfig } from './map-types/proportional-symbol/mushroom/MushroomMapConfig'
+import type { MushroomMap } from './map-types/proportional-symbol/mushroom/MushroomMap'
+
+// Composition map types
+import type { CompositionStatConfig } from './map-types/composition/CompositionStatConfig'
+import type { CoxcombMapConfig } from './map-types/composition/coxcomb/CoxcombMapConfig'
+import type { CoxcombMap } from './map-types/composition/coxcomb/CoxcombMap'
+import type { CoxcombStatConfig } from './map-types/composition/coxcomb/CoxcombStatConfig'
+import type { BarMapConfig } from './map-types/composition/bar/BarMapConfig'
+import type { BarMap } from './map-types/composition/bar/BarMap'
+import type { PieMapConfig } from './map-types/composition/pie/PieMapConfig'
+import type { PieMap } from './map-types/composition/pie/PieMap'
+import type { StripeMapConfig } from './map-types/composition/stripe/StripeMapConfig'
+import type { StripeMap } from './map-types/composition/stripe/StripeMap'
+import type { WaffleMapConfig } from './map-types/composition/waffle/WaffleMapConfig'
+import type { WaffleMap } from './map-types/composition/waffle/WaffleMap'
+
+// Spark map types
+import type { SparkMapConfig } from './map-types/spark/SparkMapConfig'
+import type { SparkMap } from './map-types/spark/SparkMap'
+import type { SparkStatConfig } from './map-types/spark/SparkStatConfig'
+
+// Flow map types
+import type { FlowMapConfig } from './map-types/flow/FlowMapConfig'
+import type { FlowMap } from './map-types/flow/FlowMap'
+
+// ==================== Core Type Exports ====================
+
+export type { MapConfig, MapType, MapInstance }
+export type EurostatMap = MapInstance
+export type { TooltipConfig } from './core/TooltipConfig'
+export type { LegendConfig } from './legend/LegendConfig'
+export type { StatConfig } from './core/stat/StatConfig'
+export type { InsetConfig } from './core/InsetConfig'
+
+// ==================== Legend Configuration Type Exports ====================
+
+// Main legend types
+export type { CategoricalLegendConfig } from './legend/CategoricalLegendConfig'
+export type { CoxcombLegendConfig } from './legend/CoxcombLegendConfig'
+export type { MushroomLegendConfig } from './legend/MushroomLegendConfig'
+export type { PieChartLegendConfig } from './legend/PieChartLegendConfig'
+export type { SparklineLegendConfig } from './legend/SparklineLegendConfig'
+export type { WaffleLegendConfig } from './legend/WaffleLegendConfig'
+export type { StripeCompositionLegendConfig } from './legend/StripeCompositionLegendConfig'
+export type { PatternFillLegendConfig } from './legend/PatternFillLegendConfig'
+
+// Choropleth legend types
+export type { BivariateLegendConfig } from './legend/choropleth/BivariateLegendConfig'
+export type { HistogramLegendConfig } from './legend/choropleth/HistogramLegendConfig'
+
+// Composition legend types
+export type { BarChartLegendConfig } from './legend/composition/BarChartLegendConfig'
+
+// Flow legend types
+export type { FlowMapLegendConfig } from './legend/flow/FlowMapLegendConfig'
+
+// Proportional symbol legend types
+export type { ProportionalSymbolsLegendConfig } from './legend/proportional-symbol/ProportionalSymbolsLegendConfig'
+
+// ==================== Map Type Exports ====================
+
+// Choropleth map types
+export type {
+    ChoroplethConfig,
+    ChoroplethMap,
+    ValueByAlphaConfig,
+    ValueByAlphaMap,
+    BivariateChoroplethConfig,
+    BivariateChoroplethMap,
+    TrivariateChoroplethConfig,
+    TrivariateChoroplethMap,
+}
+
+// Categorical map types
+export type { CategoricalMapConfig, CategoricalMap }
+
+// Proportional symbol map types
+export type { ProportionalSymbolConfig, ProportionalSymbolMap, MushroomMapConfig, MushroomMap }
+
+// Composition map types
+export type {
+    CompositionStatConfig,
+    CoxcombMapConfig,
+    CoxcombMap,
+    CoxcombStatConfig,
+    BarMapConfig,
+    BarMap,
+    PieMapConfig,
+    PieMap,
+    StripeMapConfig,
+    StripeMap,
+    WaffleMapConfig,
+    WaffleMap,
+}
+
+// Spark map types
+export type { SparkMapConfig, SparkMap, SparkStatConfig }
+
+// Flow map types
+export type { FlowMapConfig, FlowMap }
+
+// ==================== Pattern Fill Options ====================
+
+/**
+ * Options for fill pattern definitions
+ */
+export interface FillPatternOptions {
+    shape?: 'circle' | 'square'
+    patternSize?: number
+    minSize?: number
+    maxSize?: number
+    bckColor?: string
+    symbColor?: string
+}
+
+// ==================== Main Factory Function ====================
+
+/**
+ * Main factory function to create maps
+ *
+ * @param type - The type of map to create
+ * @param config - Configuration object
+ * @returns A map object with builder pattern methods
+ *
+ * @example
+ * ```typescript
+ * import eurostatmap from 'eurostatmap';
+ *
+ * const map = eurostatmap.map('choropleth', {
+ *   title: 'Population Density',
+ *   stat: { eurostatDatasetCode: 'demo_r_d3dens' }
+ * });
+ * map.build();
+ * ```
+ */
+export function map(type: 'choropleth' | 'ch', config?: ChoroplethConfig): ChoroplethMap
+export function map(type: 'proportionalSymbol' | 'proportionalSymbols' | 'ps', config?: ProportionalSymbolConfig): ProportionalSymbolMap
+export function map(type: 'categorical' | 'ct', config?: CategoricalMapConfig): CategoricalMap
+export function map(type: 'bivariateChoropleth' | 'chbi', config?: BivariateChoroplethConfig): BivariateChoroplethMap
+export function map(type: 'trivariateChoropleth' | 'ternary' | 'chtri', config?: TrivariateChoroplethConfig): TrivariateChoroplethMap
+export function map(type: 'alpha' | 'valueByAlpha', config?: ValueByAlphaConfig): ValueByAlphaMap
+export function map(type: 'coxcomb' | 'polar', config?: CoxcombMapConfig): CoxcombMap
+export function map(type: 'bar' | 'barComposition', config?: BarMapConfig): BarMap
+export function map(type: 'stripeComposition' | 'scomp' | 'stripe', config?: StripeMapConfig): StripeMap
+export function map(type: 'waffle', config?: WaffleMapConfig): WaffleMap
+export function map(type: 'mushroom', config?: MushroomMapConfig): MushroomMap
+export function map(type: 'pieChart' | 'pie', config?: PieMapConfig): PieMap
+export function map(type: 'sparkline' | 'spark' | 'sparklines', config?: SparkMapConfig): SparkMap
+export function map(type: 'flow' | 'flowmap', config?: FlowMapConfig): FlowMap
+export function map(type: MapType, config?: MapConfig): MapInstance
+
+// ==================== Utility Functions ====================
+
+/**
+ * Get a function that defines fill patterns for legends
+ *
+ * @param opts - Pattern options
+ * @returns Function that creates pattern definitions
+ */
+export function getFillPatternDefinitionFunction(opts?: FillPatternOptions): (svg: any, numberOfClasses: number) => void
+
+/**
+ * @deprecated Use getFillPatternDefinitionFunction instead
+ */
+export function getFillPatternDefinitionFun(opts?: FillPatternOptions): (svg: any, numberOfClasses: number) => void
+
+/**
+ * Get default labels for the map
+ */
+export function getDefaultLabels(): { [key: string]: string }
+
+/**
+ * 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]
+ */
+export function projectFromMap(map: MapInstance, x: number, y: number): [number, number]
+
+/**
+ * Project geographic coordinates to map pixel space
+ *
+ * @param map - The map object
+ * @param lon - Longitude
+ * @param lat - Latitude
+ * @returns [x, y] pixel coordinates
+ */
+export function projectToMap(map: MapInstance, lon: number, lat: number): [number, number]
+
+/**
+ * Library version
+ */
+export const version: string
+
+// ==================== Default Export ====================
+
+declare const eurostatmap: {
+    map: typeof map
+    getFillPatternDefinitionFunction: typeof getFillPatternDefinitionFunction
+    getFillPatternDefinitionFun: typeof getFillPatternDefinitionFun
+    getDefaultLabels: typeof getDefaultLabels
+    projectFromMap: typeof projectFromMap
+    projectToMap: typeof projectToMap
+    version: typeof version
+}
+
+export default eurostatmap

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

@@ -0,0 +1,13 @@
+import { LegendConfig } from './LegendConfig'
+
+/**
+ * Configuration for categorical map legends.
+ * Used to display a legend with colored rectangles representing different categories.
+ */
+export interface CategoricalLegendConfig extends LegendConfig {
+    /**
+     * Custom order for legend elements. If not specified, uses the domain order from the classifier.
+     * Provide an array of category codes in the desired display order.
+     */
+    order?: string[]
+}

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

@@ -0,0 +1,85 @@
+import { LegendConfig } from './LegendConfig'
+
+/**
+ * Configuration for size legend in coxcomb (polar area) charts.
+ */
+export interface CoxcombSizeLegendConfig {
+    /** Title for the size legend. */
+    title?: string | null
+
+    /** Padding between title and legend content in pixels. @default 15 */
+    titlePadding?: number
+
+    /** Custom values to display in the size legend. If not specified, values are auto-generated. */
+    values?: number[] | null
+
+    /** Custom labels for the size legend values. */
+    labels?: string[] | null
+
+    /** Custom formatter function for legend labels. */
+    labelFormatter?: ((value: number) => string) | null
+}
+
+/**
+ * Configuration for color legend in coxcomb (polar area) charts.
+ */
+export interface CoxcombColorLegendConfig {
+    /** Title for the color legend. */
+    title?: string | null
+
+    /** Padding between title and legend content in pixels. @default 15 */
+    titlePadding?: number
+
+    /** Top margin for the color legend in pixels. @default 23 */
+    marginTop?: number
+
+    /** Offset adjustments for labels. @default { x: 5, y: 5 } */
+    labelOffsets?: { x: number; y: number }
+
+    /** Width of color swatches in pixels. @default 25 */
+    shapeWidth?: number
+
+    /** Height of color swatches in pixels. @default 20 */
+    shapeHeight?: number
+
+    /** Padding between swatches in pixels. @default 1 */
+    shapePadding?: number
+
+    /** Whether to show a "no data" item. @default true */
+    noData?: boolean
+
+    /** Text label for "no data" item. @default 'No data' */
+    noDataText?: string
+}
+
+/**
+ * Configuration for time legend in coxcomb (polar area) charts.
+ */
+export interface CoxcombTimeLegendConfig {
+    /** Title for the time legend. */
+    title?: string | null
+
+    /** Padding between title and legend content in pixels. @default 15 */
+    titlePadding?: number
+
+    /** Top margin for the time legend in pixels. @default 20 */
+    marginTop?: number
+
+    /** Radius of the time legend circle in pixels. @default 35 */
+    radius?: number
+}
+
+/**
+ * Configuration for coxcomb (polar area) chart legends.
+ * Supports separate sub-legends for size, color, and time dimensions.
+ */
+export interface CoxcombLegendConfig extends LegendConfig {
+    /** Configuration for the wedge size legend. */
+    sizeLegend?: Partial<CoxcombSizeLegendConfig>
+
+    /** Configuration for the color/category legend. */
+    colorLegend?: Partial<CoxcombColorLegendConfig>
+
+    /** Configuration for the time period legend. */
+    timeLegend?: Partial<CoxcombTimeLegendConfig>
+}

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

@@ -0,0 +1,43 @@
+/**
+ * Parent configuration for map legends. Each map type will extend this with its own specific properties, but these are the common ones that apply to all legend types.
+ */
+export interface LegendConfig {
+    x?: number
+    y?: number
+    width?: number
+    height?: number
+
+    title?: string
+    titleWidth?: number
+    titleFontSize?: number
+
+    // Box styling
+    boxWidth?: number
+    boxHeight?: number
+    boxPadding?: number
+    boxCornerRadius?: number
+
+    // Shape styling (for proportional symbol legends)
+    shapeWidth?: number
+    shapeHeight?: number
+    shapePadding?: number
+
+    // Label styling
+    labelFontSize?: number
+    labelOffset?: number
+    labelWrap?: number
+    labelDecimalPlaces?: number
+
+    // Orientation
+    orientation?: 'vertical' | 'horizontal'
+    ascending?: boolean
+
+    // Cells (for manual legend specification)
+    cells?: any[]
+
+    // No data label
+    noData?: boolean
+    noDataText?: string
+
+    [key: string]: any
+}

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

@@ -0,0 +1,56 @@
+import { LegendConfig } from './LegendConfig'
+
+/**
+ * Configuration for size legend in mushroom (dual semi-circle) charts.
+ */
+export interface MushroomSizeLegendConfig {
+    /** Top margin for the size legend in pixels. @default 15 */
+    marginTop?: number
+
+    /** Custom values to display in the size legend (when using single scale). Raw data values. */
+    values?: number[]
+
+    /** Custom values for variable 1 side (when using independent scales). Raw data values. */
+    valuesV1?: number[]
+
+    /** Custom values for variable 2 side (when using independent scales). Raw data values. */
+    valuesV2?: number[]
+
+    /** Custom labels for the size legend values. */
+    labels?: string[] | null
+
+    /** Custom labels for variable 1 side. */
+    labelsV1?: string[] | null
+
+    /** Custom labels for variable 2 side. */
+    labelsV2?: string[] | null
+
+    /** Vertical spacing between legend items in pixels. @default 2 */
+    shapePadding?: number
+
+    /** Offset adjustments for labels. @default { x: 5, y: 0 } */
+    labelOffsets?: { x: number; y: number }
+}
+
+/**
+ * Configuration for color legend in mushroom (dual semi-circle) charts.
+ */
+export interface MushroomColorLegendConfig {
+    /** Top margin for the color legend in pixels. @default 5 */
+    marginTop?: number
+
+    /** Offset adjustments for labels. @default { x: 5, y: 5 } */
+    labelOffsets?: { x: number; y: number }
+}
+
+/**
+ * Configuration for mushroom (dual semi-circle) chart legends.
+ * Mushroom charts show two variables as semi-circles forming a circle, with size and color dimensions.
+ */
+export interface MushroomLegendConfig extends LegendConfig {
+    /** Configuration for the mushroom size legend. */
+    sizeLegend?: Partial<MushroomSizeLegendConfig>
+
+    /** Configuration for the color/category legend. */
+    colorLegend?: Partial<MushroomColorLegendConfig>
+}

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

@@ -0,0 +1,11 @@
+import { LegendConfig } from './LegendConfig'
+
+/**
+ * Configuration for pattern fill legends.
+ * Used to display a legend showing hatching/pattern options for regions.
+ * The pattern fill legend is typically appended below the main choropleth legend.
+ */
+export interface PatternFillLegendConfig extends LegendConfig {
+    // Inherits all properties from LegendConfig
+    // Pattern fill legends use the base configuration for display
+}

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

@@ -0,0 +1,68 @@
+import { LegendConfig } from './LegendConfig'
+
+/**
+ * Configuration for size legend in pie chart maps.
+ */
+export interface PieChartSizeLegendConfig {
+    /** Title for the size legend. */
+    title?: string | null
+
+    /** Padding between title and legend content in pixels. @default 10 */
+    titlePadding?: number
+
+    /** Custom values to display in the size legend. If not specified, values are auto-generated. */
+    values?: number[] | null
+
+    /** Custom formatter function for legend labels. */
+    labelFormatter?: ((value: number) => string) | undefined
+
+    /** Whether to show a "no data" item. @default false */
+    noData?: boolean
+
+    /** Text label for "no data" item. @default 'No data' */
+    noDataText?: string
+}
+
+/**
+ * Configuration for color legend in pie chart maps.
+ */
+export interface PieChartColorLegendConfig {
+    /** Title for the color legend. */
+    title?: string | null
+
+    /** Padding between title and legend content in pixels. @default 10 */
+    titlePadding?: number
+
+    /** Top margin (distance from size legend) in pixels. @default 33 */
+    marginTop?: number
+
+    /** Offset adjustments for labels. @default { x: 5, y: 5 } */
+    labelOffsets?: { x: number; y: number }
+
+    /** Width of color swatches in pixels. @default 25 */
+    shapeWidth?: number
+
+    /** Height of color swatches in pixels. @default 20 */
+    shapeHeight?: number
+
+    /** Padding between swatches in pixels. @default 1 */
+    shapePadding?: number
+
+    /** Whether to show a "no data" item. @default true */
+    noData?: boolean
+
+    /** Text label for "no data" item. @default 'No data' */
+    noDataText?: string
+}
+
+/**
+ * Configuration for pie chart map legends.
+ * Supports separate legends for pie size and slice colors.
+ */
+export interface PieChartLegendConfig extends LegendConfig {
+    /** Configuration for the pie size legend. Set to false to hide. */
+    sizeLegend?: Partial<PieChartSizeLegendConfig> | false
+
+    /** Configuration for the color/category legend. Set to false to hide. */
+    colorLegend?: Partial<PieChartColorLegendConfig> | false
+}

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

@@ -0,0 +1,68 @@
+import { LegendConfig } from './LegendConfig'
+
+/**
+ * Configuration for scale legend in sparkline maps.
+ */
+export interface SparklineScaleLegendConfig {
+    /** Title for the scale legend section. */
+    title?: string | null
+
+    /** Padding between title and chart in pixels. @default 5 */
+    titlePadding?: number
+
+    /** Whether to show an example sparkline with averaged data. @default false */
+    showExampleChart?: boolean
+
+    /** Whether to show the region with maximum value. @default true */
+    showMaxRegion?: boolean
+
+    /** Custom example data for the sparkline. If null, uses averaged data. */
+    exampleData?: number[] | null
+
+    /** Number of ticks on Y axis. @default 5 */
+    tickCount?: number
+
+    /** Custom tick format function for Y axis values. */
+    tickFormat?: ((value: number) => string) | null
+
+    /** Whether to show X axis with date labels. @default true */
+    showXAxis?: boolean
+
+    /** Rotation angle for X axis labels in degrees. @default -45 */
+    xAxisRotation?: number
+
+    /** Step for showing X axis ticks (1 = every tick, 2 = every other, etc.). @default 1 */
+    xAxisTickStep?: number
+
+    /** Margins around the sparkline cell. Defaults to match the map's sparkline chart margin. */
+    margin?: { top: number; right: number; bottom: number; left: number }
+
+    /** Opacity of the sparkline. @default 0.5 */
+    lineOpacity?: number
+
+    /** Stroke width of the sparkline. @default 1 */
+    lineStrokeWidth?: number
+}
+
+/**
+ * Configuration for no data legend in sparkline maps.
+ */
+export interface SparklineNoDataLegendConfig {
+    /** Whether to show the no data legend item. @default true */
+    show?: boolean
+
+    /** Text label for "no data" item. @default 'No data' */
+    text?: string
+}
+
+/**
+ * Configuration for sparkline map legends.
+ * Shows the Y-axis scale and optionally an example sparkline chart.
+ */
+export interface SparklineLegendConfig extends LegendConfig {
+    /** Configuration for the scale legend showing Y-axis range. */
+    scaleLegend?: Partial<SparklineScaleLegendConfig>
+
+    /** Configuration for the no data legend. Set to false to hide. */
+    noDataLegend?: Partial<SparklineNoDataLegendConfig> | false
+}

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

@@ -0,0 +1,11 @@
+import { LegendConfig } from './LegendConfig'
+
+/**
+ * Configuration for stripe composition map legends.
+ * Used to display a legend with colored rectangles representing different categories
+ * in stripe composition maps (regions divided into colored stripes showing composition).
+ */
+export interface StripeCompositionLegendConfig extends LegendConfig {
+    // Inherits all properties from LegendConfig
+    // No additional specific properties beyond the base legend configuration
+}

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

@@ -0,0 +1,74 @@
+import { LegendConfig } from './LegendConfig'
+
+/**
+ * Configuration for size legend in waffle chart maps.
+ */
+export interface WaffleSizeLegendConfig {
+    /** Title for the size legend. */
+    title?: string | null
+
+    /** Padding between title and legend content in pixels. @default 10 */
+    titlePadding?: number
+
+    /** Custom values to display in the size legend. If not specified, values are auto-generated. */
+    values?: number[] | null
+
+    /** Custom formatter function for legend labels. */
+    labelFormatter?: ((value: number) => string) | undefined
+
+    /** Simplified grid size for size legend examples (e.g., 5 means 5x5 = 25 cells). @default 5 */
+    gridSize?: number
+
+    /** Padding between cells in size legend in pixels. @default 0.5 */
+    cellPadding?: number
+
+    /** Whether to show a "no data" item. @default false */
+    noData?: boolean
+
+    /** Text label for "no data" item. @default 'No data' */
+    noDataText?: string
+}
+
+/**
+ * Configuration for color legend in waffle chart maps.
+ */
+export interface WaffleColorLegendConfig {
+    /** Title for the color legend. */
+    title?: string | null
+
+    /** Padding between title and legend content in pixels. @default 10 */
+    titlePadding?: number
+
+    /** Top margin (distance from size legend) in pixels. @default 33 */
+    marginTop?: number
+
+    /** Offset adjustments for labels. @default { x: 5, y: 5 } */
+    labelOffsets?: { x: number; y: number }
+
+    /** Width of color swatches in pixels. @default 25 */
+    shapeWidth?: number
+
+    /** Height of color swatches in pixels. @default 20 */
+    shapeHeight?: number
+
+    /** Padding between swatches in pixels. @default 1 */
+    shapePadding?: number
+
+    /** Whether to show a "no data" item. @default true */
+    noData?: boolean
+
+    /** Text label for "no data" item. @default 'No data' */
+    noDataText?: string
+}
+
+/**
+ * Configuration for waffle chart map legends.
+ * Waffle charts display data as grids of small squares, with colors representing categories.
+ */
+export interface WaffleLegendConfig extends LegendConfig {
+    /** Configuration for the waffle size legend. */
+    sizeLegend?: Partial<WaffleSizeLegendConfig>
+
+    /** Configuration for the color/category legend. Set to false to hide. */
+    colorLegend?: Partial<WaffleColorLegendConfig> | false
+}