or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-superset-ui--legacy-plugin-chart-world-map

Legacy world map chart plugin for Apache Superset with choropleth mapping and bubble overlays

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/@superset-ui/legacy-plugin-chart-world-map@0.18.x

To install, run

npx @tessl/cli install tessl/npm-superset-ui--legacy-plugin-chart-world-map@0.18.0

Legacy Plugin Chart World Map

A legacy world map chart plugin for Apache Superset that enables interactive geographical data visualization through choropleth mapping and bubble overlays. Built with D3.js and datamaps, it provides both React and functional APIs for creating world maps in Superset dashboards.

Package Information

Package Name: @superset-ui/legacy-plugin-chart-world-map
Package Type: npm
Language: JavaScript/TypeScript
Installation: npm install @superset-ui/legacy-plugin-chart-world-map

Core Imports

import WorldMapChartPlugin from '@superset-ui/legacy-plugin-chart-world-map';

For ES modules:

import WorldMapChartPlugin from '@superset-ui/legacy-plugin-chart-world-map';

For CommonJS:

const WorldMapChartPlugin = require('@superset-ui/legacy-plugin-chart-world-map');

Basic Usage

import WorldMapChartPlugin from '@superset-ui/legacy-plugin-chart-world-map';

// Create and register the plugin with Superset
const worldMapPlugin = new WorldMapChartPlugin();
// Note: Registration with Superset is typically handled by the framework

// Use with SuperChart
<SuperChart
  chartType="world-map"
  width={600}
  height={600}
  formData={{
    entity: 'country',
    countryFieldtype: 'cca2',
    colorBy: 'metric',
    showBubbles: false,
    maxBubbleSize: 25,
    // ... other configuration options
  }}
  queriesData={[{
    data: [
      {
        country: 'US',
        name: 'United States',
        latitude: 39.8283,
        longitude: -98.5795,
        m1: 1000,    // Primary metric (for choropleth)
        m2: 500      // Secondary metric (for bubble size)
      },
      // ... more country data
    ],
  }]}
/>

Architecture

The plugin is built around several key components:

WorldMapChartPlugin: Main plugin class that extends ChartPlugin and integrates with Superset's chart system
WorldMap Function: Core D3.js-based visualization implementation using datamaps
ReactWorldMap Component: Styled React component wrapper that integrates the WorldMap function with Superset's theming
transformProps Function: Data transformation layer that converts Superset chart props to WorldMap component props
Control Panel Configuration: TypeScript configuration object defining the chart customization interface
ColorBy Enum: Utility enum defining color mapping strategies

Capabilities

Plugin Registration

Main plugin class for registering the world map chart with Superset.

class WorldMapChartPlugin extends ChartPlugin {
  constructor();
}

The plugin includes comprehensive metadata:

interface ChartMetadata {
  category: string;           // 'Map'
  credits: string[];          // ['http://datamaps.github.io/']
  description: string;        // Chart description
  exampleGallery: { url: string }[];
  name: string;              // 'World Map'
  tags: string[];            // Chart classification tags
  thumbnail: string;         // Thumbnail image path
  useLegacyApi: boolean;     // true
  behaviors: Behavior[];     // [Behavior.DRILL_TO_DETAIL]
}

World Map Visualization

Core D3.js-based world map visualization function.

function WorldMap(element: HTMLElement, props: WorldMapProps): void;

interface WorldMapProps {
  data: CountryData[];
  width: number;
  height: number;
  maxBubbleSize: number;
  showBubbles: boolean;
  linearColorScheme: string;
  color: string;
  colorBy: ColorBy;
  colorScheme: string;
  countryFieldtype: 'name' | 'cioc' | 'cca2' | 'cca3';
  entity: string;
  sliceId: string | number;
  theme: SupersetTheme;
  onContextMenu: (x: number, y: number, filters: Filter[]) => void;
  inContextMenu: boolean;
}

interface CountryData {
  country: string;       // Country code (format depends on countryFieldtype)
  latitude: number;      // Country latitude for bubble placement
  longitude: number;     // Country longitude for bubble placement
  name: string;          // Display name for tooltips
  m1: number;           // Primary metric for choropleth coloring
  m2: number;           // Secondary metric for bubble sizing
}

interface Filter {
  col: string;
  op: string;
  val: any;
  formattedVal: any;
}

React Component

Styled React wrapper component that integrates WorldMap with Superset's theming system.

interface WorldMapComponent {
  (props: { className: string } & WorldMapProps): JSX.Element;
}

// The default export is a styled component
const StyledWorldMapComponent: React.ComponentType<{
  className: string;
} & WorldMapProps>;

Props Transformation

Transform Superset chart props to WorldMap component props.

function transformProps(chartProps: SupersetChartProps): WorldMapProps;

interface SupersetChartProps {
  width: number;
  height: number;
  formData: FormData;
  queriesData: QueryData[];
  hooks: {
    onContextMenu: (x: number, y: number, filters: Filter[]) => void;
  };
  inContextMenu: boolean;
}

interface FormData {
  countryFieldtype: 'name' | 'cioc' | 'cca2' | 'cca3';
  entity: string;
  maxBubbleSize: string;
  showBubbles: boolean;
  linearColorScheme: string;
  colorPicker: { r: number; g: number; b: number };
  colorBy: ColorBy;
  colorScheme: string;
  sliceId: string | number;
}

interface QueryData {
  data: CountryData[];
}

Control Panel Configuration

Configuration interface for chart customization in Superset.

interface ControlPanelConfig {
  controlPanelSections: ControlSection[];
  controlOverrides: Record<string, any>;
  formDataOverrides: (formData: any) => any;
}

interface ControlSection {
  label: string;
  expanded: boolean;
  controlSetRows: ControlSetRow[];
}

type ControlSetRow = (string | ControlConfig)[];

interface ControlConfig {
  name: string;
  config: {
    type: string;
    label: string;
    default?: any;
    choices?: [string, string][];
    options?: [string, string][];
    description?: string;
    renderTrigger?: boolean;
    freeForm?: boolean;
    visibility?: (state: any) => boolean;
  };
}

Color Mapping Utilities

Color mapping strategies and utilities for the chart.

enum ColorBy {
  metric = 'metric',
  country = 'country'
}

Core Types

Type definitions used throughout the plugin.

interface SupersetTheme {
  colors: {
    grayscale: {
      light2: string;
      light5: string;
      dark2: string;
    };
  };
}

enum Behavior {
  DRILL_TO_DETAIL = 'DRILL_TO_DETAIL'
}

interface ChartPlugin {
  constructor(config: {
    loadChart: () => Promise<any>;
    metadata: ChartMetadata;
    transformProps: (props: any) => any;
    controlPanel: ControlPanelConfig;
  }): void;
}

Configuration Options

Country Field Types

The chart supports different country code formats:

'name': Full country names
'cioc': International Olympic Committee codes
'cca2': ISO 3166-1 alpha-2 codes (default)
'cca3': ISO 3166-1 alpha-3 codes

Color Mapping

Two coloring strategies are supported:

'metric': Countries colored by primary metric values using sequential color schemes
'country': Countries colored categorically using distinct colors per country

Bubble Overlays

When showBubbles is true, circular overlays are rendered on the map:

Size determined by secondary metric (m2) values
Color matches the base chart color
Positioning based on country latitude/longitude coordinates
Maximum size controlled by maxBubbleSize parameter

Error Handling

The chart handles several error conditions:

Invalid country codes: Countries with codes not found in the datamaps dataset are filtered out
Missing data: Countries without data are rendered with default fill color
Context menu errors: Invalid context menu interactions are logged with warnings
Right-click handling: Malformed country data prevents context menu creation

Usage Examples

Basic Choropleth Map

const formData = {
  entity: 'country_code',
  countryFieldtype: 'cca2',
  colorBy: 'metric',
  linearColorScheme: 'blues',
  showBubbles: false
};

const data = [
  { country: 'US', name: 'United States', m1: 1000, m2: 500, latitude: 39.8, longitude: -98.6 },
  { country: 'CA', name: 'Canada', m1: 750, m2: 300, latitude: 56.1, longitude: -106.3 },
  { country: 'MX', name: 'Mexico', m1: 500, m2: 200, latitude: 23.6, longitude: -102.5 }
];

Bubble Overlay Map

const formData = {
  entity: 'country_code',
  countryFieldtype: 'cca3',
  colorBy: 'country',
  colorScheme: 'supersetColors',
  showBubbles: true,
  maxBubbleSize: 50
};

const data = [
  { country: 'USA', name: 'United States', m1: 1000, m2: 5000, latitude: 39.8, longitude: -98.6 },
  { country: 'CAN', name: 'Canada', m1: 750, m2: 3000, latitude: 56.1, longitude: -106.3 }
];

Custom Color Configuration

const formData = {
  colorPicker: { r: 255, g: 0, b: 0 }, // Red base color
  colorBy: 'metric',
  linearColorScheme: 'reds'
};