0
# Legacy Plugin Chart World Map
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: @superset-ui/legacy-plugin-chart-world-map
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install @superset-ui/legacy-plugin-chart-world-map`
10

11
## Core Imports
12

13
```typescript
14
import WorldMapChartPlugin from '@superset-ui/legacy-plugin-chart-world-map';
15
```
16

17
For ES modules:
18
```javascript
19
import WorldMapChartPlugin from '@superset-ui/legacy-plugin-chart-world-map';
20
```
21

22
For CommonJS:
23
```javascript
24
const WorldMapChartPlugin = require('@superset-ui/legacy-plugin-chart-world-map');
25
```
26

27
## Basic Usage
28

29
```javascript
30
import WorldMapChartPlugin from '@superset-ui/legacy-plugin-chart-world-map';
31

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

36
// Use with SuperChart
37
<SuperChart
38
  chartType="world-map"
39
  width={600}
40
  height={600}
41
  formData={{
42
    entity: 'country',
43
    countryFieldtype: 'cca2',
44
    colorBy: 'metric',
45
    showBubbles: false,
46
    maxBubbleSize: 25,
47
    // ... other configuration options
48
  }}
49
  queriesData={[{
50
    data: [
51
      {
52
        country: 'US',
53
        name: 'United States',
54
        latitude: 39.8283,
55
        longitude: -98.5795,
56
        m1: 1000,    // Primary metric (for choropleth)
57
        m2: 500      // Secondary metric (for bubble size)
58
      },
59
      // ... more country data
60
    ],
61
  }]}
62
/>
63
```
64

65
## Architecture
66

67
The plugin is built around several key components:
68

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

76
## Capabilities
77

78
### Plugin Registration
79

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

82
```typescript { .api }
83
class WorldMapChartPlugin extends ChartPlugin {
84
  constructor();
85
}
86
```
87

88
The plugin includes comprehensive metadata:
89

90
```typescript { .api }
91
interface ChartMetadata {
92
  category: string;           // 'Map'
93
  credits: string[];          // ['http://datamaps.github.io/']
94
  description: string;        // Chart description
95
  exampleGallery: { url: string }[];
96
  name: string;              // 'World Map'
97
  tags: string[];            // Chart classification tags
98
  thumbnail: string;         // Thumbnail image path
99
  useLegacyApi: boolean;     // true
100
  behaviors: Behavior[];     // [Behavior.DRILL_TO_DETAIL]
101
}
102
```
103

104
### World Map Visualization
105

106
Core D3.js-based world map visualization function.
107

108
```typescript { .api }
109
function WorldMap(element: HTMLElement, props: WorldMapProps): void;
110

111
interface WorldMapProps {
112
  data: CountryData[];
113
  width: number;
114
  height: number;
115
  maxBubbleSize: number;
116
  showBubbles: boolean;
117
  linearColorScheme: string;
118
  color: string;
119
  colorBy: ColorBy;
120
  colorScheme: string;
121
  countryFieldtype: 'name' | 'cioc' | 'cca2' | 'cca3';
122
  entity: string;
123
  sliceId: string | number;
124
  theme: SupersetTheme;
125
  onContextMenu: (x: number, y: number, filters: Filter[]) => void;
126
  inContextMenu: boolean;
127
}
128

129
interface CountryData {
130
  country: string;       // Country code (format depends on countryFieldtype)
131
  latitude: number;      // Country latitude for bubble placement
132
  longitude: number;     // Country longitude for bubble placement
133
  name: string;          // Display name for tooltips
134
  m1: number;           // Primary metric for choropleth coloring
135
  m2: number;           // Secondary metric for bubble sizing
136
}
137

138
interface Filter {
139
  col: string;
140
  op: string;
141
  val: any;
142
  formattedVal: any;
143
}
144
```
145

146
### React Component
147

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

150
```typescript { .api }
151
interface WorldMapComponent {
152
  (props: { className: string } & WorldMapProps): JSX.Element;
153
}
154

155
// The default export is a styled component
156
const StyledWorldMapComponent: React.ComponentType<{
157
  className: string;
158
} & WorldMapProps>;
159
```
160

161

162
### Props Transformation
163

164
Transform Superset chart props to WorldMap component props.
165

166
```typescript { .api }
167
function transformProps(chartProps: SupersetChartProps): WorldMapProps;
168

169
interface SupersetChartProps {
170
  width: number;
171
  height: number;
172
  formData: FormData;
173
  queriesData: QueryData[];
174
  hooks: {
175
    onContextMenu: (x: number, y: number, filters: Filter[]) => void;
176
  };
177
  inContextMenu: boolean;
178
}
179

180
interface FormData {
181
  countryFieldtype: 'name' | 'cioc' | 'cca2' | 'cca3';
182
  entity: string;
183
  maxBubbleSize: string;
184
  showBubbles: boolean;
185
  linearColorScheme: string;
186
  colorPicker: { r: number; g: number; b: number };
187
  colorBy: ColorBy;
188
  colorScheme: string;
189
  sliceId: string | number;
190
}
191

192
interface QueryData {
193
  data: CountryData[];
194
}
195
```
196

197
### Control Panel Configuration
198

199
Configuration interface for chart customization in Superset.
200

201
```typescript { .api }
202
interface ControlPanelConfig {
203
  controlPanelSections: ControlSection[];
204
  controlOverrides: Record<string, any>;
205
  formDataOverrides: (formData: any) => any;
206
}
207

208
interface ControlSection {
209
  label: string;
210
  expanded: boolean;
211
  controlSetRows: ControlSetRow[];
212
}
213

214
type ControlSetRow = (string | ControlConfig)[];
215

216
interface ControlConfig {
217
  name: string;
218
  config: {
219
    type: string;
220
    label: string;
221
    default?: any;
222
    choices?: [string, string][];
223
    options?: [string, string][];
224
    description?: string;
225
    renderTrigger?: boolean;
226
    freeForm?: boolean;
227
    visibility?: (state: any) => boolean;
228
  };
229
}
230
```
231

232
### Color Mapping Utilities
233

234
Color mapping strategies and utilities for the chart.
235

236
```typescript { .api }
237
enum ColorBy {
238
  metric = 'metric',
239
  country = 'country'
240
}
241
```
242

243
### Core Types
244

245
Type definitions used throughout the plugin.
246

247
```typescript { .api }
248
interface SupersetTheme {
249
  colors: {
250
    grayscale: {
251
      light2: string;
252
      light5: string;
253
      dark2: string;
254
    };
255
  };
256
}
257

258
enum Behavior {
259
  DRILL_TO_DETAIL = 'DRILL_TO_DETAIL'
260
}
261

262
interface ChartPlugin {
263
  constructor(config: {
264
    loadChart: () => Promise<any>;
265
    metadata: ChartMetadata;
266
    transformProps: (props: any) => any;
267
    controlPanel: ControlPanelConfig;
268
  }): void;
269
}
270
```
271

272
## Configuration Options
273

274
### Country Field Types
275

276
The chart supports different country code formats:
277

278
- `'name'`: Full country names
279
- `'cioc'`: International Olympic Committee codes
280
- `'cca2'`: ISO 3166-1 alpha-2 codes (default)  
281
- `'cca3'`: ISO 3166-1 alpha-3 codes
282

283
### Color Mapping
284

285
Two coloring strategies are supported:
286

287
- `'metric'`: Countries colored by primary metric values using sequential color schemes
288
- `'country'`: Countries colored categorically using distinct colors per country
289

290
### Bubble Overlays
291

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

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

299
## Error Handling
300

301
The chart handles several error conditions:
302

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

308
## Usage Examples
309

310
### Basic Choropleth Map
311

312
```javascript
313
const formData = {
314
  entity: 'country_code',
315
  countryFieldtype: 'cca2',
316
  colorBy: 'metric',
317
  linearColorScheme: 'blues',
318
  showBubbles: false
319
};
320

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

328
### Bubble Overlay Map
329

330
```javascript
331
const formData = {
332
  entity: 'country_code',
333
  countryFieldtype: 'cca3',
334
  colorBy: 'country',
335
  colorScheme: 'supersetColors',
336
  showBubbles: true,
337
  maxBubbleSize: 50
338
};
339

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

346
### Custom Color Configuration
347

348
```javascript
349
const formData = {
350
  colorPicker: { r: 255, g: 0, b: 0 }, // Red base color
351
  colorBy: 'metric',
352
  linearColorScheme: 'reds'
353
};
354
```