0
# Superset UI Legacy Plugin Chart Sankey Loop
1

2
A React-based Sankey diagram visualization plugin with loop support for Apache Superset. This plugin provides interactive data visualization capabilities for exploring complex network relationships and flow data that includes cyclic relationships, extending traditional Sankey diagrams to handle loops in data flows.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
import SankeyChartPlugin from '@superset-ui/legacy-plugin-chart-sankey-loop';
15
```
16

17
For CommonJS:
18

19
```javascript
20
const SankeyChartPlugin = require('@superset-ui/legacy-plugin-chart-sankey-loop');
21
```
22

23
## Basic Usage
24

25
```javascript
26
import SankeyChartPlugin from '@superset-ui/legacy-plugin-chart-sankey-loop';
27

28
// Register the plugin with Superset
29
const sankeyPlugin = new SankeyChartPlugin();
30
sankeyPlugin.configure({ key: 'sankey-loop' }).register();
31
```
32

33
For use with SuperChart:
34

35
```javascript
36
import { SuperChart } from '@superset-ui/core';
37

38
<SuperChart
39
  chartType="sankey-loop"
40
  width={600}
41
  height={600}
42
  formData={{
43
    groupby: ['source', 'target'],
44
    metric: 'value',
45
    color_scheme: 'd3Category10',
46
    // ... other form data options
47
  }}
48
  queriesData={[{
49
    data: [
50
      { source: 'A', target: 'B', value: 10 },
51
      { source: 'B', target: 'C', value: 15 },
52
      { source: 'C', target: 'A', value: 5 }, // Loop back to A
53
      // ... more link data
54
    ]
55
  }]}
56
/>
57
```
58

59
## Architecture
60

61
The plugin is built around the Superset chart plugin architecture and includes:
62

63
- **Chart Plugin**: `SankeyChartPlugin` class extending Superset's `ChartPlugin`
64
- **React Component**: `ReactSankeyLoop` component for React integration
65
- **D3 Visualization**: `SankeyLoop` D3-based rendering engine with loop support
66
- **Data Transformation**: `transformProps` function for Superset data integration
67
- **Control Panel**: Configuration interface for chart customization
68

69
## Capabilities
70

71
### SankeyChartPlugin
72

73
Main plugin class for registering and configuring the Sankey diagram with loops visualization in Superset.
74

75
```javascript { .api }
76
/**
77
 * Main chart plugin class for Sankey diagram with loops visualization
78
 * Extends ChartPlugin from @superset-ui/core
79
 */
80
class SankeyChartPlugin extends ChartPlugin {
81
  constructor();
82
}
83
```
84

85
The plugin is configured with:
86
- **Chart metadata**: Name, description, thumbnail, and credits
87
- **Dynamic chart loading**: Lazy-loads the React component
88
- **Data transformation**: Processes Superset query data into chart format
89
- **Control panel**: Provides UI controls for chart configuration
90

91
### Plugin Registration
92

93
Register the plugin with Superset's chart registry.
94

95
```javascript { .api }
96
/**
97
 * Configure the plugin with registration key and optional settings
98
 * @param config - Plugin configuration object with key and other options
99
 * @param replace - If true, replace entire config; otherwise merge
100
 * @returns Configured plugin instance for method chaining
101
 */
102
configure(config: { key: string, [key: string]: any }, replace?: boolean): SankeyChartPlugin;
103

104
/**
105
 * Register the plugin with Superset's chart registries
106
 * Registers in ChartMetadataRegistry, ChartComponentRegistry, 
107
 * ChartControlPanelRegistry, and ChartTransformPropsRegistry
108
 * @returns Plugin instance for method chaining
109
 */
110
register(): SankeyChartPlugin;
111

112
/**
113
 * Remove the plugin from all Superset registries
114
 * @returns Plugin instance for method chaining
115
 */
116
unregister(): SankeyChartPlugin;
117

118
/**
119
 * Reset plugin configuration to defaults
120
 * @returns Plugin instance for method chaining
121
 */
122
resetConfig(): SankeyChartPlugin;
123
```
124

125
**Usage Example:**
126

127
```javascript
128
import SankeyChartPlugin from '@superset-ui/legacy-plugin-chart-sankey-loop';
129

130
const plugin = new SankeyChartPlugin();
131
plugin.configure({ key: 'sankey-loop' }).register();
132
```
133

134
### SankeyLoop D3 Visualization Component
135

136
Core D3-based visualization function that renders the Sankey diagram with loop support. This is the underlying rendering engine used by the React wrapper.
137

138
```javascript { .api }
139
/**
140
 * Renders a Sankey diagram with loop support using D3.js
141
 * @param element - DOM element to render the chart into
142
 * @param props - Chart configuration and data
143
 */
144
function SankeyLoop(element: HTMLElement, props: SankeyLoopProps): void;
145

146
interface SankeyLoopProps {
147
  /** Array of link data representing flows between nodes */
148
  data: Array<{
149
    source: string;
150
    target: string;
151
    value: number;
152
  }>;
153
  /** Chart width in pixels */
154
  width: number;
155
  /** Chart height in pixels */
156
  height: number;
157
  /** Color scheme identifier */
158
  colorScheme: string;
159
  /** Slice identifier for consistent coloring */
160
  sliceId: string | number;
161
  /** Chart margins (optional, uses default if not provided) */
162
  margin?: {
163
    top: number;
164
    right: number;
165
    bottom: number;
166
    left: number;
167
  };
168
}
169
```
170

171
**Key Implementation Details:**
172
- Uses `d3-sankey-diagram` library version ^0.7.3 for loop support
173
- Applies `sankeyDiagram()` layout with automatic node positioning
174
- Colors links based on source node using categorical color scheme
175
- Adds interactive tooltips showing flow values and percentages
176
- Sets SVG class `superset-legacy-chart-sankey-loop` for styling
177
- Default margins: `{ top: 0, right: 80, bottom: 0, left: 80 }` to accommodate labels
178

179
### Data Transformation
180

181
The `transformProps` function processes Superset query data into the format expected by the visualization component.
182

183
```javascript { .api }
184
/**
185
 * Transforms Superset chart props into format expected by SankeyLoop component
186
 * @param chartProps - Raw props from Superset including query data and form data
187
 * @returns Transformed props for the visualization component
188
 */
189
function transformProps(chartProps: SupersetChartProps): SankeyLoopProps;
190

191
interface SupersetChartProps {
192
  /** Chart dimensions */
193
  width: number;
194
  height: number;
195
  /** Chart configuration from control panel */
196
  formData: {
197
    colorScheme: string;
198
    sliceId: string | number;
199
  };
200
  /** Query results from Superset */
201
  queriesData: Array<{
202
    data: Array<{
203
      source: string;
204
      target: string;
205
      value: number;
206
    }>;
207
  }>;
208
  /** Chart margins */
209
  margin: {
210
    top: number;
211
    right: number;
212
    bottom: number;
213
    left: number;
214
  };
215
}
216
```
217

218
The transformation extracts the first query's data and passes through dimensions, color scheme, and margin settings.
219

220
### Data Format
221

222
The chart expects data in a specific link format for representing flows between nodes.
223

224
```javascript { .api }
225
/**
226
 * Link data structure for Sankey diagram
227
 */
228
interface LinkData {
229
  /** Source node identifier */
230
  source: string;
231
  /** Target node identifier */  
232
  target: string;
233
  /** Flow value between source and target */
234
  value: number;
235
}
236

237
/**
238
 * Chart props after transformation
239
 */
240
interface ChartProps {
241
  /** Chart width in pixels */
242
  width: number;
243
  /** Chart height in pixels */
244
  height: number;
245
  /** Array of link data representing flows */
246
  data: LinkData[];
247
  /** Color scheme identifier (e.g., 'd3Category10') */
248
  colorScheme: string;
249
  /** Chart margins */
250
  margin: {
251
    top: number;
252
    right: number;
253
    bottom: number;
254
    left: number;
255
  };
256
  /** Slice identifier for color consistency */
257
  sliceId: string | number;
258
}
259
```
260

261
### Control Panel Configuration
262

263
Control panel sections and options available in Superset UI.
264

265
```javascript { .api }
266
/**
267
 * Control panel configuration with sections and controls
268
 */
269
interface ControlPanelConfig {
270
  controlPanelSections: Array<{
271
    label: string;
272
    expanded: boolean;
273
    controlSetRows: string[][];
274
  }>;
275
  controlOverrides: {
276
    groupby: {
277
      label: string;
278
      description: string;
279
    };
280
  };
281
}
282
```
283

284
**Available Control Sections:**
285
- **Time Range**: Legacy time range controls (`legacyRegularTime`)
286
- **Query**: Core data selection controls
287
  - `groupby`: Source and target column selection (labeled "Source / Target")
288
  - `metric`: Metric/value column for flow weights
289
  - `adhoc_filters`: Additional filtering conditions
290
  - `row_limit`: Maximum number of records to process
291
- **Chart Options**: Visual customization
292
  - `color_scheme`: Color palette selection for nodes/links
293

294
**Form Data Structure:**
295
```javascript { .api }
296
interface FormData {
297
  /** Source and target columns array */
298
  groupby: string[];
299
  /** Metric column for flow values */
300
  metric: string;
301
  /** Selected color scheme identifier */
302
  color_scheme: string;
303
  /** Maximum number of rows to process */
304
  row_limit: number;
305
  /** Additional filter conditions */
306
  adhoc_filters: AdhocFilter[];
307
}
308
```
309

310
### Styling and CSS Classes
311

312
The chart applies specific CSS classes for customization.
313

314
```css { .api }
315
/* Main container class for the entire chart */
316
.superset-legacy-chart-sankey-loop {
317
  /* Root SVG container */
318
}
319

320
/* Node rectangle styling */
321
.superset-legacy-chart-sankey-loop .node rect {
322
  cursor: move;
323
  fill-opacity: 0.9;
324
  shape-rendering: crispEdges;
325
}
326

327
/* Node text label styling */
328
.superset-legacy-chart-sankey-loop .node text {
329
  pointer-events: none;
330
  text-shadow: 0 1px 0 #fff;
331
}
332

333
/* Link default styling */
334
.superset-legacy-chart-sankey-loop .link {
335
  fill: none;
336
  stroke: #000;
337
  stroke-opacity: 0.2;
338
}
339

340
/* Link hover effects */
341
.superset-legacy-chart-sankey-loop .link:hover {
342
  stroke-opacity: 0.5;
343
}
344

345
/* Link path elements */
346
.superset-legacy-chart-sankey-loop .link path {
347
  opacity: 0.2;
348
  stroke-opacity: 0;
349
}
350

351
.superset-legacy-chart-sankey-loop .link:hover path {
352
  opacity: 0.5;
353
}
354

355
/* Link text labels showing values */
356
.superset-legacy-chart-sankey-loop .link text {
357
  fill: #666;
358
  font-size: 10px;
359
}
360

361
.superset-legacy-chart-sankey-loop .link:hover text {
362
  opacity: 1;
363
}
364
```
365

366
## Error Handling
367

368
The plugin follows Superset's error handling patterns. Common issues include:
369

370
- **Data format errors**: Ensure data contains `source`, `target`, and `value` fields
371
- **Missing dependencies**: Verify peer dependencies `@superset-ui/core` and `@superset-ui/chart-controls` are installed
372
- **Registration errors**: Ensure plugin is registered before use in charts
373

374
## Dependencies
375

376
```javascript { .api }
377
/**
378
 * Required peer dependencies
379
 */
380
interface PeerDependencies {
381
  "@superset-ui/chart-controls": string;
382
  "@superset-ui/core": string;
383
}
384

385
/**
386
 * Direct dependencies
387
 */
388
interface Dependencies {
389
  "d3-sankey-diagram": "^0.7.3";
390
  "d3-selection": "^1.4.0";
391
  "prop-types": "^15.6.2";
392
}
393
```
394

395
## Key Features
396

397
- **Loop Support**: Handles cyclic relationships in data flows unlike traditional Sankey diagrams
398
- **D3.js Integration**: Leverages `d3-sankey-diagram` for optimized SVG rendering
399
- **Interactive Tooltips**: Hover interactions with value and percentage displays
400
- **Categorical Colors**: Supports Superset's color scheme system
401
- **Responsive Design**: Configurable margins and dimensions
402
- **Superset Integration**: Full compatibility with Superset's dashboard and exploration interface
403
- **Legacy API Support**: Uses Superset's legacy API format for data queries