eurostat-map 4.3.58 → 4.4.1

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

@@ -0,0 +1,198 @@
+import type { MapInstance } from './MapInstance'
+
+/**
+ * Ensures a <g> element with the specified class exists within the container.
+ * If it exists, clears its contents; if not, creates it.
+ */
+export function ensureGroup(container: any, className: string): any
+
+/**
+ * Updates or creates a CSS rule for a given selector.
+ */
+export function updateCSSRule(selector: string, property: string, value: string): void
+
+/**
+ * Gets the computed font size from a CSS class name.
+ */
+export function getFontSizeFromClass(className: string): number
+
+/**
+ * Gets a computed CSS property value from a CSS class name.
+ */
+export function getCSSPropertyFromClass(className: string, propertyName: string): string
+
+/**
+ * Applies inline styles from computed CSS to an SVG element and its descendants.
+ * Useful for exporting SVGs with CSS styles.
+ */
+export function applyInlineStylesFromCSS(svgElement: SVGElement): void
+
+/**
+ * Applies computed styles to an SVG element for export.
+ */
+export function applyComputedStylesToSVG(svg: SVGElement): void
+
+/**
+ * Ensures an SVG element has explicit width and height attributes.
+ */
+export function ensureSvgSize(svg: SVGSVGElement): void
+
+/**
+ * Converts a bounding box array to a GeoJSON polygon.
+ */
+export function getBBOXAsGeoJSON(bb: [number, number, number, number]): any
+
+/**
+ * Converts a JSON-stat object to an index keyed by geographic codes.
+ */
+export function jsonstatToIndex(jsData: any): Record<string, any>
+
+/**
+ * Converts CSV data to an index keyed by geographic codes.
+ */
+export function csvToIndex(csvData: string, geoCol: string, valueCol: string): Record<string, number>
+
+/**
+ * Formats a number with spaces as thousand separators.
+ */
+export function spaceAsThousandSeparator(number: number): string
+
+/**
+ * Base URL for Eurostat REST API.
+ */
+export const getEstatRestDataURLBase: string
+
+/**
+ * Constructs a URL for fetching Eurostat data.
+ */
+export function getEstatDataURL(datasetCode: string, filters: any, lang?: string, format?: string): string
+
+/**
+ * Gets a URL parameter by name.
+ */
+export function getURLParameterByName(name: string): string | null
+
+/**
+ * Gets a URL parameter by name (alias).
+ */
+export function getParameterByName(name: string): string | null
+
+/**
+ * Checks if a map has a diverging color scheme.
+ */
+export function checkIfDiverging(map: MapInstance): boolean
+
+/**
+ * Centers a diverging color function around a point of divergence.
+ */
+export function centerDivergingColorFunction(colorFunc: any, domain: number[], pointOfDivergence?: number, transform?: (d: number) => number): any
+
+/**
+ * Generates a unique ID with an optional prefix.
+ */
+export function generateUniqueId(prefix: string): string
+
+/**
+ * Eurostat flag codes and descriptions.
+ */
+export const flags: Record<string, string>
+
+/**
+ * Executes a function for all insets recursively.
+ */
+export function executeForAllInsets(
+    /** Insets. */
+    insets: any,
+    /** Main svg id. */
+    mainSvgId: string,
+    functionToExecute: (inset: MapInstance, ...args: any[]) => void,
+    /** Parameter. */
+    parameter?: any,
+    /** Parameter2. */
+    parameter2?: any
+): void
+
+/**
+ * Converts first letter of a string to uppercase.
+ */
+export function upperCaseFirstLetter(string: string): string
+
+/**
+ * Converts a string to lowercase except for first letters of words.
+ */
+export function lowerCaseAllWordsExceptFirstLetters(string: string): string
+
+/**
+ * Creates a download URL for an SVG element.
+ */
+export function getDownloadURL(svgNode: SVGElement): string
+
+/**
+ * Serializes an SVG element to a string.
+ */
+export function serialize(svg: SVGElement): string
+
+/**
+ * Rasterizes an SVG element to a canvas blob.
+ */
+export function rasterize(svg: SVGElement): Promise<Blob>
+
+/**
+ * Converts hex color to RGB object.
+ */
+export function hexToRgb(hex: string): { r: number; g: number; b: number }
+
+/**
+ * Blends multiple colors using multiply blending mode.
+ */
+export function multiplyBlendMultipleHex(colors: string[]): string
+
+/**
+ * Blends colors using average blending.
+ */
+export function averageBlendHex(colors: string[]): string
+
+/**
+ * Interpolates color intensity.
+ */
+export function interpolateIntensity(baseColor: string, idx: number): string
+
+/**
+ * Converts rectangle coordinates to an SVG path string.
+ */
+export function convertRectanglesToPaths(x: number, y: number, width: number, height: number): string
+
+/**
+ * Determines appropriate text color (black/white) for a given background color.
+ */
+export function getTextColorForBackground(backgroundColor: string): string
+
+/**
+ * Gets the CSS selector for data-driven regions on a map.
+ */
+export function getRegionsSelector(map: MapInstance): string
+
+/**
+ * Gets the CSS selector for legend region highlighting.
+ */
+export function getLegendRegionsSelector(map: MapInstance): string
+
+/**
+ * Gets an approximate geographic bounding box for the current map view.
+ */
+export function getApproxCurrentGeoBbox(map: MapInstance): number[]
+
+/**
+ * Gets a region element by ID from the map.
+ */
+export function getRegionById(map: MapInstance, id: string): any
+
+/**
+ * Compact number formatter (e.g., 1000 → "1K").
+ */
+export const compactFormatter: Intl.NumberFormat
+
+/**
+ * Long number formatter.
+ */
+export const longFormatter: Intl.NumberFormat

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

@@ -0,0 +1,21 @@
+import type { MapInstance } from './MapInstance'
+
+/**
+ * Defines the D3 zoom behavior for a map instance.
+ * Handles both geographic zoom and grid cartogram zoom.
+ * @param map - The map instance to add zoom behavior to
+ */
+export function defineMapZoom(map: MapInstance): void
+
+/**
+ * Defines geographic zoom behavior with pan locking and snap-back.
+ * @param map - The map instance
+ */
+export function defineGeographicZoom(map: MapInstance): void
+
+/**
+ * Sets the map view to a specific position and zoom level.
+ * @param map - The map instance
+ * @param pos - Position object with x, y coordinates and z zoom level
+ */
+export function setMapView(map: MapInstance, pos: { x?: number; y?: number; z?: number }): void

package/build/types/index.d.ts

@@ -0,0 +1,253 @@
+/**
+ * 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'
+export type { CoastalMarginSettings } from './core/decoration/CoastalMarginSettings'
+export type { GridCartogramSettings, GridCartogramMargins } from './core/GridCartogramSettings'
+export type { DorlingSettings, DorlingStrength } from './core/DorlingSettings'
+
+// ==================== Legend Configuration Type Exports ====================
+
+// Main legend types
+export type { CategoricalLegendConfig } from './legend/CategoricalLegendConfig'
+export type { MushroomLegendConfig } from './legend/MushroomLegendConfig'
+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'
+export type { CoxcombLegendConfig } from './legend/composition/CoxcombLegendConfig'
+export type { PieChartLegendConfig } from './legend/composition/PieChartLegendConfig'
+export type { WaffleLegendConfig } from './legend/composition/WaffleLegendConfig'
+export type { StripeCompositionLegendConfig } from './legend/composition/StripeCompositionLegendConfig'
+export type {
+    SparklineLegendConfig,
+    SparklineScaleLegendConfig,
+    SparklineColorLegendConfig,
+    SparklineNoDataLegendConfig,
+} from './legend/composition/SparklineLegendConfig'
+
+// 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. */
+    shape?: 'circle' | 'square'
+    /** Pattern size. */
+    patternSize?: number
+    /** Min size. */
+    minSize?: number
+    /** Max size. */
+    maxSize?: number
+    /** Bck color. */
+    bckColor?: string
+    /** Symb color. */
+    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
+
+/**
+ * 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. */
+    map: typeof map
+    /** Get fill pattern definition function. */
+    getFillPatternDefinitionFunction: typeof getFillPatternDefinitionFunction
+    /** Get fill pattern definition fun. */
+    getFillPatternDefinitionFun: typeof getFillPatternDefinitionFun
+    /** Get default labels. */
+    getDefaultLabels: typeof getDefaultLabels
+    /** Project from map. */
+    projectFromMap: typeof projectFromMap
+    /** Project to map. */
+    projectToMap: typeof projectToMap
+    /** Version. */
+    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,51 @@
+/**
+ * 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 {
+    /** Legend origin x-coordinate in pixels. */
+    x?: number
+    /** Legend origin y-coordinate in pixels. */
+    y?: number
+    /** Legend width in pixels. */
+    width?: number
+    /** Legend height in pixels. */
+    height?: number
+
+    /** Legend title text. */
+    title?: string
+    /** Legend title font size in pixels. */
+    titleFontSize?: number
+
+    /** Box styling. */
+    /** Inner spacing around legend content. */
+    boxPadding?: number
+
+    /** Shape styling (for proportional symbol legends). */
+    /** Symbol swatch width in pixels. */
+    shapeWidth?: number
+    /** Symbol swatch height in pixels. */
+    shapeHeight?: number
+    /** Horizontal gap between shape and label. */
+    shapePadding?: number
+
+    /** Label styling. */
+    /** Label font size in pixels. */
+    labelFontSize?: number
+    /** Pixel offset applied to labels. */
+    labelOffset?: number
+
+    /** Legend layout direction. */
+    orientation?: 'vertical' | 'horizontal'
+    /** Sort legend entries in ascending order when true. */
+    ascending?: boolean
+
+    /** Manual legend cell definitions. */
+    cells?: any[]
+
+    /** Whether to display the no-data legend item. */
+    noData?: boolean
+    /** Label used for no-data legend item. */
+    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
+}