0
# Encodable Configuration
1

2
Configuration system for integrating the encodable library with Superset's color schemes, formatters, and scales to enable seamless visual encoding in word cloud visualizations.
3

4
## Capabilities
5

6
### Configure Encodable
7

8
Main configuration function that sets up encodable library integration with Superset's theming and formatting systems.
9

10
```typescript { .api }
11
/**
12
 * Configures the encodable library with Superset-specific resolvers
13
 * Sets up number formatting, time formatting, color schemes, and color scales
14
 * Must be called before using encodable features in the word cloud
15
 */
16
function configureEncodable(): void;
17
```
18

19
**Usage:**
20

21
```typescript
22
import { configureEncodable } from '@superset-ui/plugin-chart-word-cloud';
23

24
// Configure encodable (typically done once during plugin initialization)
25
configureEncodable();
26

27
// Now encodable features work with Superset's theming system
28
```
29

30
This function is automatically called during plugin initialization, so manual invocation is typically not required.
31

32
## Resolver Configuration
33

34
The configuration sets up four key resolvers that bridge encodable with Superset's systems:
35

36
### Number Format Resolver
37

38
Integrates Superset's number formatting system with encodable.
39

40
```typescript { .api }
41
/**
42
 * Number format resolver using Superset's formatting system
43
 * Enables consistent number formatting across charts
44
 */
45
type NumberFormatResolver = (format?: string) => (value: number) => string;
46
```
47

48
**Features:**
49
- Uses `getNumberFormatter` from `@superset-ui/core`
50
- Supports all Superset number format patterns
51
- Consistent formatting with other Superset charts
52
- Handles currency, percentage, and custom number formats
53

54
### Time Format Resolver
55

56
Integrates Superset's time formatting with support for local/UTC time zones.
57

58
```typescript { .api }
59
/**
60
 * Time format resolver with local time support
61
 * @param options - Formatting options
62
 * @param options.format - Time format string (optional)
63
 * @param options.formatInLocalTime - Whether to format in local time (default: false)
64
 * @returns Configured time formatter function
65
 */
66
type TimeFormatResolver = (options?: {
67
  format?: string;
68
  formatInLocalTime?: boolean;
69
}) => (value: Date | number) => string;
70
```
71

72
**Features:**
73
- UTC and local time formatting support
74
- Uses Superset's time formatter registry
75
- Automatic prefix handling for local time (`LOCAL_PREFIX`)
76
- Default format fallback from registry
77

78
**Usage Example:**
79

80
```typescript
81
// UTC time formatting (default)
82
const utcFormatter = timeFormat({ format: '%Y-%m-%d' });
83

84
// Local time formatting
85
const localFormatter = timeFormat({ 
86
  format: '%Y-%m-%d %H:%M', 
87
  formatInLocalTime: true 
88
});
89
```
90

91
### Color Scheme Resolver
92

93
Integrates Superset's color scheme registries for both categorical and sequential color schemes.
94

95
```typescript { .api }
96
/**
97
 * Color scheme resolver supporting categorical and sequential schemes
98
 * @param options - Color scheme options
99
 * @param options.name - Scheme name (optional)
100
 * @param options.type - Scheme type: 'categorical' or 'sequential' (default: 'categorical')
101
 * @returns Color scheme configuration or undefined if not found
102
 */
103
type ColorSchemeResolver = (options?: {
104
  name?: string;
105
  type?: 'categorical' | 'sequential';
106
}) => ColorScheme | undefined;
107

108
interface ColorScheme {
109
  type: 'categorical' | 'sequential';
110
  // Additional scheme properties from Superset registries
111
}
112
```
113

114
**Supported Schemes:**
115

116
- **Categorical**: Uses `getCategoricalSchemeRegistry()` from Superset
117
  - Examples: 'category10', 'tableau10', 'superset_colors'
118
- **Sequential**: Uses `getSequentialSchemeRegistry()` from Superset  
119
  - Examples: 'blues', 'greens', 'viridis'
120

121
**Usage Example:**
122

123
```typescript
124
// Get categorical color scheme
125
const categorical = colorSchemeResolver({ 
126
  name: 'category10', 
127
  type: 'categorical' 
128
});
129

130
// Get sequential color scheme
131
const sequential = colorSchemeResolver({ 
132
  name: 'viridis', 
133
  type: 'sequential' 
134
});
135
```
136

137
### Categorical Color Scale Resolver
138

139
Integrates Superset's categorical color namespace system for consistent color assignment.
140

141
```typescript { .api }
142
/**
143
 * Categorical color scale resolver using Superset's color namespace
144
 * Ensures consistent colors across charts and dashboards
145
 * @param options - Color scale options
146
 * @param options.name - Color scheme name (optional)
147
 * @param options.namespace - Color namespace for consistency (optional)
148
 * @returns Categorical color scale function
149
 */
150
type CategoricalColorScaleResolver = (options?: {
151
  name?: string;
152
  namespace?: string;
153
}) => CategoricalColorScale;
154

155
type CategoricalColorScale = (value: string, sliceId?: number) => string;
156
```
157

158
**Features:**
159
- Consistent color assignment across dashboard charts
160
- Namespace support for color coordination
161
- Integration with `CategoricalColorNamespace.getScale()`
162
- Automatic color persistence and sharing
163

164
**Usage Example:**
165

166
```typescript
167
// Get color scale with namespace
168
const colorScale = colorScaleResolver({ 
169
  name: 'superset_colors',
170
  namespace: 'dashboard_colors' 
171
});
172

173
// Use color scale
174
const color1 = colorScale('category_a', 123); // Returns consistent color
175
const color2 = colorScale('category_b', 123); // Returns different consistent color
176
```
177

178
## Integration Points
179

180
### Encodable Library Setup
181

182
The configuration is applied to the global Encodable instance:
183

184
```typescript
185
Encodable
186
  .setNumberFormatResolver(getNumberFormatter)
187
  .setTimeFormatResolver(timeFormat)
188
  .setColorSchemeResolver(colorSchemeResolver)  
189
  .setCategoricalColorScaleResolver(colorScaleResolver);
190
```
191

192
### Superset Core Dependencies
193

194
The configuration integrates with these Superset core systems:
195

196
```typescript { .api }
197
// Number formatting
198
import { getNumberFormatter } from '@superset-ui/core';
199

200
// Time formatting  
201
import { 
202
  getTimeFormatter, 
203
  getTimeFormatterRegistry,
204
  LOCAL_PREFIX 
205
} from '@superset-ui/core';
206

207
// Color schemes
208
import { 
209
  getCategoricalSchemeRegistry,
210
  getSequentialSchemeRegistry 
211
} from '@superset-ui/core';
212

213
// Color namespace
214
import { CategoricalColorNamespace } from '@superset-ui/core';
215
```
216

217
### Encodable Library Dependencies
218

219
```typescript { .api }
220
import {
221
  Encodable,
222
  ColorSchemeResolver,
223
  TimeFormatResolver,
224
  CategoricalColorScaleResolver,
225
  defaultColorSchemeResolver,
226
  addPrefix
227
} from 'encodable';
228
```
229

230
## Configuration Flow
231

232
1. **Plugin Initialization**: `configureEncodable()` is called during plugin construction
233
2. **Resolver Setup**: Each resolver is configured with Superset-specific implementations
234
3. **Encodable Integration**: Global Encodable instance receives the configured resolvers
235
4. **Runtime Usage**: Word cloud component uses encodable features seamlessly
236
5. **Consistent Theming**: All visual encodings respect Superset's theming and formatting
237

238
This configuration ensures that word cloud visualizations integrate seamlessly with Superset's visual design system and maintain consistency with other chart types in dashboards.