0
# Data Transformation
1

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

4
## Capabilities
5

6
### Modern Transform Props
7

8
Transforms ChartProps to WordCloudProps for the modern plugin implementation.
9

10
```typescript { .api }
11
/**
12
 * Transform function for modern WordCloudChartPlugin
13
 * Extracts relevant properties from Superset chart props
14
 * @param chartProps - Standard Superset chart properties
15
 * @returns WordCloud component properties
16
 */
17
function transformProps(chartProps: ChartProps): WordCloudProps;
18

19
interface ChartProps {
20
  width: number;
21
  height: number;
22
  formData: WordCloudFormData;
23
  queriesData: Array<{ data: PlainObject[] }>;
24
}
25
```
26

27
**Usage Example:**
28

29
```typescript
30
import { WordCloudTransformProps } from '@superset-ui/plugin-chart-word-cloud';
31

32
const chartProps = {
33
  width: 600,
34
  height: 400,
35
  formData: {
36
    series: 'word_column',
37
    metric: 'frequency',
38
    encoding: {
39
      fontSize: { field: 'frequency', type: 'quantitative' },
40
      text: { field: 'word_column' }
41
    },
42
    rotation: 'random',
43
    sliceId: 123
44
  },
45
  queriesData: [{
46
    data: [
47
      { word_column: 'analytics', frequency: 100 },
48
      { word_column: 'dashboard', frequency: 85 }
49
    ]
50
  }]
51
};
52

53
const wordCloudProps = WordCloudTransformProps(chartProps);
54
// Returns: { data, encoding, height, rotation, width, sliceId }
55
```
56

57
### Legacy Transform Props
58

59
Transforms ChartProps to WordCloudProps for the legacy plugin implementation with automatic encoding generation.
60

61
```typescript { .api }
62
/**
63
 * Transform function for LegacyWordCloudChartPlugin
64
 * Converts legacy form data format into modern encoding structure
65
 * @param chartProps - Standard Superset chart properties with legacy form data
66
 * @returns WordCloud component properties with converted encoding
67
 */
68
function transformProps(chartProps: ChartProps): WordCloudProps;
69
```
70

71
**Legacy Form Data Conversion:**
72

73
The legacy transform automatically converts old-style form data into the modern encoding format:
74

75
```typescript
76
// Legacy form data input
77
const legacyFormData = {
78
  series: 'word_field',
79
  metric: 'count_field',
80
  colorScheme: 'category10',
81
  sizeFrom: 10,
82
  sizeTo: 80,
83
  rotation: 'square'
84
};
85

86
// Automatically converted to modern encoding
87
const modernEncoding = {
88
  color: {
89
    field: 'word_field',
90
    scale: { scheme: 'category10' },
91
    type: 'nominal'
92
  },
93
  fontSize: {
94
    field: 'count_field',
95
    scale: { range: [10, 80], zero: true },
96
    type: 'quantitative'
97
  },
98
  text: {
99
    field: 'word_field'
100
  }
101
};
102
```
103

104
### Metric Label Extraction
105

106
Helper function for extracting metric labels from various legacy metric formats.
107

108
```typescript { .api }
109
/**
110
 * Extracts metric label from legacy metric configuration
111
 * Handles string, array, and object metric formats
112
 * @param metric - Legacy metric configuration in various formats
113
 * @returns Extracted metric label or undefined
114
 */
115
function getMetricLabel(
116
  metric: string | undefined | Array<any> | { label: string }
117
): string | undefined;
118
```
119

120
**Metric Format Support:**
121

122
```typescript
123
// String format
124
getMetricLabel('sum_sales') // Returns: 'sum_sales'
125

126
// Object format with label
127
getMetricLabel({ label: 'Total Sales', column: 'sales' }) // Returns: 'Total Sales'
128

129
// Array format (uses first element)
130
getMetricLabel([
131
  { label: 'Primary Metric', column: 'metric1' },
132
  { label: 'Secondary Metric', column: 'metric2' }
133
]) // Returns: 'Primary Metric'
134

135
// Undefined/empty
136
getMetricLabel(undefined) // Returns: undefined
137
getMetricLabel([]) // Returns: undefined
138
```
139

140
## Form Data Types
141

142
### Modern Form Data
143

144
```typescript { .api }
145
interface WordCloudFormData extends QueryFormData, WordCloudVisualProps {
146
  series: string; // Field name for word text
147
}
148

149
interface WordCloudVisualProps {
150
  encoding?: Partial<WordCloudEncoding>;
151
  rotation?: RotationType;
152
}
153
```
154

155
**Properties:**
156
- **series**: Data field containing the text to display as words
157
- **encoding**: Visual encoding configuration for size, color, etc.
158
- **rotation**: Word rotation pattern ('flat', 'random', 'square')
159
- **Plus all QueryFormData properties**: metrics, filters, time range, etc.
160

161
### Legacy Form Data
162

163
```typescript { .api }
164
interface LegacyWordCloudFormData extends QueryFormData {
165
  colorScheme: string;        // Color scheme name (e.g., 'category10')
166
  rotation?: RotationType;    // Word rotation pattern
167
  series: string;             // Field name for word text
168
  sizeFrom?: number;          // Minimum font size (default: varies)
169
  sizeTo: number;             // Maximum font size
170
}
171
```
172

173
**Properties:**
174
- **colorScheme**: Named color scheme for categorical coloring
175
- **series**: Data field for both text and color grouping
176
- **sizeFrom/sizeTo**: Font size range for frequency mapping
177
- **rotation**: Word rotation pattern
178
- **Plus all QueryFormData properties**: metrics, filters, time range, etc.
179

180
## Transformation Process
181

182
### Modern Plugin Flow
183

184
1. Extract `encoding`, `rotation`, `sliceId` from `formData`
185
2. Get chart dimensions (`width`, `height`)
186
3. Extract data array from first query result
187
4. Return object with all properties for WordCloud component
188

189
### Legacy Plugin Flow
190

191
1. Extract legacy properties: `colorScheme`, `metric`, `rotation`, `series`, `sizeFrom`, `sizeTo`, `sliceId`
192
2. Use `getMetricLabel()` to extract metric field name
193
3. Build modern encoding object:
194
   - Color encoding using series field and color scheme
195
   - Font size encoding using metric field and size range
196
   - Text encoding using series field
197
4. Get chart dimensions and data
198
5. Return object with converted properties for WordCloud component
199

200
## Error Handling
201

202
The transform functions handle various edge cases:
203

204
- **Missing metric**: FontSize encoding is set to `undefined` if no metric label can be extracted
205
- **Invalid data**: Empty arrays are handled gracefully
206
- **Missing properties**: Default values are used for optional properties
207
- **Type safety**: All transforms maintain TypeScript type safety throughout the conversion process