0
# Word Cloud Component
1

2
React component for rendering interactive word cloud visualizations with configurable encoding channels and rotation options using D3.js.
3

4
## Capabilities
5

6
### WordCloud Component
7

8
Main React component that renders SVG-based word cloud visualizations.
9

10
```typescript { .api }
11
/**
12
 * Word cloud visualization component using D3.js for layout calculation
13
 * Renders words with configurable size, color, font, and rotation
14
 */
15
class WordCloud extends React.PureComponent<WordCloudProps, WordCloudState> {
16
  constructor(props: FullWordCloudProps);
17
  componentDidMount(): void;
18
  componentDidUpdate(prevProps: WordCloudProps): void;
19
  componentWillUnmount(): void;
20
  render(): React.ReactElement;
21
}
22

23
interface WordCloudProps extends WordCloudVisualProps {
24
  data: PlainObject[];
25
  height: number;
26
  width: number;
27
  sliceId: number;
28
}
29

30
interface WordCloudVisualProps {
31
  encoding?: Partial<WordCloudEncoding>;
32
  rotation?: RotationType;
33
}
34

35
interface WordCloudState {
36
  words: Word[];
37
  scaleFactor: number;
38
}
39
```
40

41
**Usage Example:**
42

43
```typescript
44
import WordCloud from '@superset-ui/plugin-chart-word-cloud';
45

46
<WordCloud
47
  data={[
48
    { text: 'analytics', count: 100, category: 'tech' },
49
    { text: 'visualization', count: 85, category: 'design' },
50
    { text: 'dashboard', count: 70, category: 'tech' }
51
  ]}
52
  width={600}
53
  height={400}
54
  sliceId={1}
55
  encoding={{
56
    text: { field: 'text' },
57
    fontSize: { field: 'count', type: 'quantitative', scale: { range: [10, 60] } },
58
    color: { field: 'category', type: 'nominal' }
59
  }}
60
  rotation="random"
61
/>
62
```
63

64
### Visual Encoding System
65

66
Configurable encoding channels for mapping data to visual properties.
67

68
```typescript { .api }
69
interface WordCloudEncoding {
70
  color: ColorEncoding;
71
  fontFamily: CategoryEncoding<string>;
72
  fontSize: NumericEncoding;
73
  fontWeight: CategoryEncoding<string | number>;
74
  text: TextEncoding;
75
}
76

77
type WordCloudEncodingConfig = {
78
  color: ['Color', string];
79
  fontFamily: ['Category', string];
80
  fontSize: ['Numeric', number];
81
  fontWeight: ['Category', string | number];
82
  text: ['Text', string];
83
};
84
```
85

86
**Encoding Channels:**
87

88
- **text**: Maps data field to displayed word text
89
- **fontSize**: Maps numeric data to font size (quantitative scale)
90
- **color**: Maps data to color (categorical or sequential scales)
91
- **fontFamily**: Maps data to font family selection
92
- **fontWeight**: Maps data to font weight (normal, bold, etc.)
93

94
**Usage Example:**
95

96
```typescript
97
const encoding: Partial<WordCloudEncoding> = {
98
  text: { field: 'word' },
99
  fontSize: {
100
    field: 'frequency',
101
    type: 'quantitative',
102
    scale: { range: [12, 72], zero: true }
103
  },
104
  color: {
105
    field: 'sentiment',
106
    type: 'nominal',
107
    scale: { scheme: 'category10' }
108
  },
109
  fontWeight: { value: 'bold' }
110
};
111
```
112

113
### Rotation Options
114

115
Configurable word rotation patterns for layout variety.
116

117
```typescript { .api }
118
type RotationType = 'flat' | 'random' | 'square';
119

120
const ROTATION: Record<RotationType, () => number> = {
121
  flat: () => 0;
122
  random: () => number; // Random rotation between -90° and 90°
123
  square: () => number; // 0° or 90° rotation
124
};
125
```
126

127
**Rotation Types:**
128

129
- **flat**: All words horizontal (0 degrees)
130
- **random**: Random rotation between -90 and 90 degrees in 30-degree increments
131
- **square**: Either horizontal (0°) or vertical (90°)
132

133
### Layout Algorithm
134

135
D3.js cloud layout integration with automatic scaling and collision detection.
136

137
```typescript { .api }
138
/**
139
 * Internal layout generation with automatic scaling
140
 * Ensures top percentage of results are always visible
141
 */
142
interface LayoutConstants {
143
  SCALE_FACTOR_STEP: 0.5;
144
  MAX_SCALE_FACTOR: 3;
145
  TOP_RESULTS_PERCENTAGE: 0.1;
146
}
147
```
148

149
**Layout Features:**
150

151
- Automatic collision detection and word placement
152
- Adaptive scaling to ensure important words are always visible
153
- Configurable padding between words (5px default)
154
- Lazy evaluation with callback-based completion
155
- Priority system ensuring top 10% of results are always displayed
156

157
**Internal Methods:**
158

159
```typescript { .api }
160
/**
161
 * Updates word cloud when data or encoding changes
162
 */
163
update(): void;
164

165
/**
166
 * Generates word cloud layout using d3-cloud
167
 * @param encoder - Configured encoder for visual mappings
168
 * @param scaleFactor - Current scale factor for fitting
169
 * @param isValid - Validation function for layout completeness
170
 */
171
generateCloud(
172
  encoder: Encoder<WordCloudEncodingConfig>,
173
  scaleFactor: number,
174
  isValid: (words: Word[]) => boolean
175
): void;
176

177
/**
178
 * Updates component state with computed word positions
179
 * @param words - Array of positioned words from d3-cloud
180
 */
181
setWords(words: Word[]): void;
182
```
183

184
### D3.js Integration
185

186
The component uses d3-cloud for word positioning and d3-scale for data mapping:
187

188
```typescript { .api }
189
// Word interface from d3-cloud
190
interface Word {
191
  text: string;
192
  size: number;
193
  x: number;
194
  y: number;
195
  rotate: number;
196
  font: string;
197
  weight: string | number;
198
}
199
```
200

201
**Cloud Layout Configuration:**
202

203
- Size: `[width * scaleFactor, height * scaleFactor]`
204
- Padding: 5 pixels between words
205
- Text accessor: Uses encoding channel for text field
206
- Font accessor: Uses encoding channel for font family
207
- Font size accessor: Uses encoding channel for size calculation
208
- Rotation accessor: Uses selected rotation function
209

210
## Default Configuration
211

212
```typescript { .api }
213
const defaultProps: Required<WordCloudVisualProps> = {
214
  encoding: {},
215
  rotation: 'flat'
216
};
217

218
const defaultEncoding = {
219
  color: { value: 'black' },
220
  fontFamily: { value: 'sans-serif' },
221
  fontSize: { value: 20 },
222
  fontWeight: { value: 'bold' },
223
  text: { value: '' }
224
};
225
```