0
# @superset-ui/core
1

2
The @superset-ui/core package provides foundational utilities, types, and components for the Apache Superset UI ecosystem. It serves as the core infrastructure layer that enables building extensible data visualization applications with robust plugin systems, formatting capabilities, and comprehensive type safety.
3

4
## Package Information
5

6
- **Package Name:** `@superset-ui/core`
7
- **Type:** TypeScript Library
8
- **Language:** TypeScript
9
- **Installation:** `npm install @superset-ui/core`
10

11
## Core Imports
12

13
### TypeScript/ES Modules
14
```typescript
15
import { 
16
  Registry, 
17
  Plugin, 
18
  formatNumber, 
19
  SuperChart,
20
  SupersetClient 
21
} from '@superset-ui/core';
22
```
23

24
### CommonJS
25
```javascript
26
const { 
27
  Registry, 
28
  Plugin, 
29
  formatNumber, 
30
  SuperChart,
31
  SupersetClient 
32
} = require('@superset-ui/core');
33
```
34

35
## Basic Usage
36

37
```typescript
38
import { 
39
  Registry, 
40
  getNumberFormatterRegistry, 
41
  formatNumber,
42
  SupersetClient 
43
} from '@superset-ui/core';
44

45
// Create a custom registry
46
const myRegistry = new Registry<string>();
47
myRegistry.registerValue('greeting', 'Hello World');
48

49
// Format numbers with built-in formatters
50
const formatted = formatNumber(',.2f', 1234.567); // "1,234.57"
51

52
// Configure API client
53
SupersetClient.configure({
54
  host: 'http://localhost:8088',
55
});
56
```
57

58
## Architecture
59

60
The @superset-ui/core package is organized into 18 core modules that provide different aspects of functionality:
61

62
### Core Infrastructure
63
- **Models & Utilities** - Registry system, plugins, utility functions
64
- **Type Definitions** - Comprehensive TypeScript types for all Superset entities
65

66
### Data & API Layer  
67
- **Data Connection** - HTTP client and API utilities
68
- **Query System** - Query building, processing, and API integration
69

70
### Visualization Framework
71
- **Chart System** - Plugin-based chart framework with component registry
72
- **Dashboard Components** - Dashboard-specific utilities and types
73

74
### Formatting & Styling
75
- **Number/Time Formatting** - Extensible formatting systems with registries
76
- **UI & Styling** - Theme system with Emotion integration
77
- **Color Management** - Color schemes and categorical color handling
78

79
### Development Tools
80
- **Validation & Math** - Input validation and expression evaluation
81
- **Internationalization** - Translation and localization support
82

83
## Capabilities
84

85
### Registry System { .api }
86

87
Core registry infrastructure for managing extensible collections:
88

89
```typescript
90
import { Registry, OverwritePolicy } from '@superset-ui/core';
91

92
class Registry<V, W = V | Promise<V>> {
93
  constructor(config?: {
94
    name?: string;
95
    overwritePolicy?: OverwritePolicy;
96
    setFirstItemAsDefault?: boolean;
97
  });
98
  
99
  registerValue(key: string, value: V): this;
100
  registerLoader(key: string, loader: () => W): this;
101
  get(key: string): V | W | undefined;
102
  getAsPromise(key: string): Promise<V>;
103
  has(key: string): boolean;
104
  clear(): this;
105
  keys(): string[];
106
  values(): (V | W | undefined)[];
107
}
108

109
enum OverwritePolicy {
110
  ALLOW = 'ALLOW',
111
  PROHIBIT = 'PROHIBIT', 
112
  WARN = 'WARN'
113
}
114
```
115

116
[→ Learn more about Core Models & Utilities](./core-models.md)
117

118
### Number Formatting { .api }
119

120
Comprehensive number formatting with extensible formatters:
121

122
```typescript
123
import { formatNumber, getNumberFormatter } from '@superset-ui/core';
124

125
// Format numbers using format strings
126
formatNumber(format: string, value: number): string;
127
formatNumber(',.2f', 1234.567); // "1,234.57"
128
formatNumber('.1%', 0.125); // "12.5%"
129

130
// Get formatter instances
131
getNumberFormatter(format: string): NumberFormatter;
132
```
133

134
[→ Learn more about Data Formatting](./data-formatting.md)
135

136
### Chart Framework { .api }
137

138
Plugin-based chart system with React integration:
139

140
```typescript
141
import { SuperChart, ChartPlugin } from '@superset-ui/core';
142

143
interface SuperChartProps {
144
  chartType: string;
145
  width?: number;
146
  height?: number;
147
  formData?: QueryFormData;
148
  queryData?: ChartDataResponseResult;
149
}
150

151
// Main chart component
152
const SuperChart: React.ComponentType<SuperChartProps>;
153

154
// Chart plugin base class
155
class ChartPlugin extends Plugin {
156
  constructor(config: {
157
    Chart: React.ComponentType<any>;
158
    metadata: ChartMetadata;
159
    transformProps?: TransformProps;
160
    buildQuery?: BuildQueryFunction;
161
  });
162
}
163
```
164

165
[→ Learn more about Plugin System](./plugin-system.md)
166

167
### API Client { .api }
168

169
HTTP client for Superset API communication:
170

171
```typescript
172
import { SupersetClient, callApi } from '@superset-ui/core';
173

174
// Configure global client
175
SupersetClient.configure(config: {
176
  host?: string;
177
  headers?: { [key: string]: string };
178
  fetchRetryOptions?: FetchRetryOptions;
179
});
180

181
// Make API calls
182
callApi(config: {
183
  url: string;
184
  method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
185
  body?: BodyInit;
186
  headers?: HeadersInit;
187
}): Promise<Response>;
188
```
189

190
[→ Learn more about Data Connection](./data-connection.md)
191

192
### Theme System { .api }
193

194
Comprehensive theming with Emotion integration:
195

196
```typescript
197
import { 
198
  useTheme, 
199
  ThemeProvider, 
200
  styled, 
201
  css,
202
  SupersetTheme 
203
} from '@superset-ui/core';
204

205
// Theme hook
206
useTheme(): SupersetTheme;
207

208
// Styled components
209
const StyledDiv = styled.div`
210
  color: ${({ theme }) => theme.colors.primary.base};
211
`;
212

213
// Theme provider
214
<ThemeProvider theme={supersetTheme}>
215
  {children}
216
</ThemeProvider>
217
```
218

219
[→ Learn more about UI & Styling](./ui-styling.md)
220

221
### Internationalization { .api }
222

223
Translation and localization support:
224

225
```typescript
226
import { t, tn } from '@superset-ui/core';
227

228
// Basic translation
229
t(text: string): string;
230
t('Hello World');
231

232
// Pluralized translation  
233
tn(singular: string, plural: string, count: number): string;
234
tn('item', 'items', count);
235
```
236

237
[→ Learn more about Translation](./translation.md)
238

239
### Validation & Math { .api }
240

241
Input validation and mathematical expression evaluation:
242

243
```typescript
244
import { 
245
  validateNumber, 
246
  validateInteger, 
247
  evalExpression 
248
} from '@superset-ui/core';
249

250
// Validation functions
251
validateNumber(value: unknown): string | false;
252
validateInteger(value: unknown): string | false;
253

254
// Math expressions
255
evalExpression(expression: string, value: number): number;
256
evalExpression('x > 10', 15); // 1 (true)
257
```
258

259
[→ Learn more about Validation & Math](./validation-math.md)
260

261
## Related Documentation
262

263
- [Core Models & Utilities](./core-models.md) - Registry system, plugins, utility functions
264
- [Translation](./translation.md) - Internationalization and localization
265
- [Data Connection](./data-connection.md) - HTTP client and API utilities  
266
- [Dashboard Components](./dashboard.md) - Dashboard-specific types and utilities
267
- [Plugin System](./plugin-system.md) - Chart plugins and dynamic loading
268
- [Data Formatting](./data-formatting.md) - Number and time formatting
269
- [UI & Styling](./ui-styling.md) - Theme system and styled components
270
- [Validation & Math](./validation-math.md) - Input validation and math expressions