0
# Superset UI Word Cloud Plugin
1

2
A comprehensive word cloud chart plugin for Apache Superset that creates interactive visualizations from text frequency data. Built with TypeScript and React, it leverages D3.js to create visually appealing word clouds with configurable scaling, color schemes, and layout options through the Superset chart control panel.
3

4
## Package Information
5

6
- **Package Name**: @superset-ui/plugin-chart-word-cloud
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @superset-ui/plugin-chart-word-cloud`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  WordCloudChartPlugin, 
16
  LegacyWordCloudChartPlugin,
17
  WordCloudTransformProps,
18
  configureEncodable,
19
  type WordCloudFormData,
20
  type WordCloudProps
21
} from '@superset-ui/plugin-chart-word-cloud';
22
```
23

24
For CommonJS:
25

26
```javascript
27
const { 
28
  WordCloudChartPlugin, 
29
  LegacyWordCloudChartPlugin,
30
  WordCloudTransformProps,
31
  configureEncodable
32
} = require('@superset-ui/plugin-chart-word-cloud');
33
```
34

35
## Basic Usage
36

37
```typescript
38
import { WordCloudChartPlugin } from '@superset-ui/plugin-chart-word-cloud';
39

40
// Register the plugin with Superset
41
new WordCloudChartPlugin()
42
  .configure({ key: 'word-cloud' })
43
  .register();
44

45
// Use with SuperChart
46
import { SuperChart } from '@superset-ui/core';
47

48
<SuperChart
49
  chartType="word-cloud"
50
  width={600}
51
  height={400}
52
  formData={{
53
    series: 'word_column',
54
    metric: 'count',
55
    rotation: 'random',
56
    encoding: {
57
      fontSize: { field: 'count', type: 'quantitative' },
58
      color: { field: 'category', type: 'nominal' },
59
      text: { field: 'word_column' }
60
    }
61
  }}
62
  queriesData={[{
63
    data: [
64
      { word_column: 'data', count: 100, category: 'tech' },
65
      { word_column: 'visualization', count: 85, category: 'tech' },
66
      { word_column: 'analytics', count: 70, category: 'business' }
67
    ]
68
  }]}
69
/>
70
```
71

72
## Architecture
73

74
The plugin is built around several key components:
75

76
- **Plugin Classes**: Modern (`WordCloudChartPlugin`) and legacy (`LegacyWordCloudChartPlugin`) implementations for different Superset versions
77
- **Chart Component**: React-based `WordCloud` component using D3.js for rendering
78
- **Transform Functions**: Data transformation utilities for converting Superset chart props to component props
79
- **Encoding System**: Configurable visual encoding channels (color, fontSize, text, fontFamily, fontWeight) using the encodable library
80
- **Control Panel**: Superset chart control configuration for user customization
81

82
## Capabilities
83

84
### Chart Plugin Registration
85

86
Core plugin classes for registering word cloud charts with Superset, supporting both modern and legacy API versions.
87

88
```typescript { .api }
89
class WordCloudChartPlugin extends ChartPlugin<WordCloudFormData> {
90
  constructor();
91
}
92

93
class LegacyWordCloudChartPlugin extends ChartPlugin<LegacyWordCloudFormData> {
94
  constructor();
95
}
96
```
97

98
[Plugin Classes](./plugin-classes.md)
99

100
### Word Cloud Visualization
101

102
React component for rendering interactive word cloud visualizations with configurable encoding channels and rotation options.
103

104
```typescript { .api }
105
interface WordCloudProps {
106
  data: PlainObject[];
107
  height: number;
108
  width: number;
109
  sliceId: number;
110
  encoding?: Partial<WordCloudEncoding>;
111
  rotation?: RotationType;
112
}
113

114
type RotationType = 'flat' | 'random' | 'square';
115
```
116

117
[Word Cloud Component](./word-cloud-component.md)
118

119
### Data Transformation
120

121
Transform functions that convert Superset chart properties into word cloud component properties, handling both modern and legacy form data formats.
122

123
```typescript { .api }
124
function WordCloudTransformProps(chartProps: ChartProps): WordCloudProps;
125

126
function getMetricLabel(
127
  metric: LegacyWordCloudFormData['metric']
128
): string | undefined;
129
```
130

131
[Data Transformation](./data-transformation.md)
132

133
### Encodable Configuration
134

135
Configuration system for integrating the encodable library with Superset's color schemes, formatters, and scales.
136

137
```typescript { .api }
138
function configureEncodable(): void;
139
```
140

141
[Encodable Configuration](./encodable-configuration.md)
142

143
### Control Panel Configuration
144

145
User interface controls for chart customization within Superset's explore view, including data selection, formatting options, and validation rules.
146

147
```typescript { .api }
148
interface ControlPanelConfig {
149
  controlPanelSections: ControlPanelSection[];
150
  controlOverrides?: Record<string, Partial<ControlConfig>>;
151
}
152
```
153

154
[Control Panel](./control-panel.md)
155

156
## Constants
157

158
```typescript { .api }
159
const ROTATION: Record<RotationType, () => number> = {
160
  flat: () => 0,
161
  random: () => Math.floor(seedRandom() * 6 - 3) * 30,
162
  square: () => Math.floor(seedRandom() * 2) * 90,
163
};
164

165
const SCALE_FACTOR_STEP = 0.5;
166
const MAX_SCALE_FACTOR = 3;
167
const TOP_RESULTS_PERCENTAGE = 0.1;
168
```
169

170
## Types
171

172
```typescript { .api }
173
interface WordCloudFormData extends QueryFormData, WordCloudVisualProps {
174
  series: string;
175
}
176

177
interface LegacyWordCloudFormData extends QueryFormData {
178
  colorScheme: string;
179
  rotation?: RotationType;
180
  series: string;
181
  sizeFrom?: number;
182
  sizeTo: number;
183
}
184

185
interface WordCloudVisualProps {
186
  encoding?: Partial<WordCloudEncoding>;
187
  rotation?: RotationType;
188
}
189

190
type WordCloudEncoding = DeriveEncoding<WordCloudEncodingConfig>;
191

192
type WordCloudEncodingConfig = {
193
  color: ['Color', string];
194
  fontFamily: ['Category', string];
195
  fontSize: ['Numeric', number];
196
  fontWeight: ['Category', string | number];
197
  text: ['Text', string];
198
};
199

200
type DeriveEncoding<T> = {
201
  [K in keyof T]: EncodingSpec<T[K][1]>;
202
};
203

204
interface EncodingSpec<T = any> {
205
  field?: string;
206
  value?: T;
207
  type?: 'nominal' | 'ordinal' | 'quantitative' | 'temporal';
208
  scale?: {
209
    scheme?: string;
210
    range?: [number, number];
211
    zero?: boolean;
212
  };
213
}
214

215
interface WordCloudState {
216
  words: Word[];
217
  scaleFactor: number;
218
}
219

220
interface Word {
221
  text: string;
222
  size: number;
223
  x: number;
224
  y: number;
225
  rotate: number;
226
  font: string;
227
  weight: string | number;
228
}
229

230
type PlainObject = Record<string, any>;
231
```