0
# @superset-ui/legacy-plugin-chart-calendar
1

2
@superset-ui/legacy-plugin-chart-calendar is a Superset chart plugin that provides calendar heatmap visualization for time-series data. It renders data as color-coded cells in a calendar format, making it ideal for identifying patterns, trends, and outliers in temporal data over days, weeks, months, or years.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
import CalendarChartPlugin from "@superset-ui/legacy-plugin-chart-calendar";
15
```
16

17
For importing utilities (not commonly needed in typical usage):
18

19
```javascript
20
// Note: Utilities are internal and not exported from main entry
21
// They are only accessible from built lib structure
22
import { getFormattedUTCTime } from "@superset-ui/legacy-plugin-chart-calendar/lib/utils";
23
```
24

25
## Basic Usage
26

27
```javascript
28
import CalendarChartPlugin from "@superset-ui/legacy-plugin-chart-calendar";
29

30
// Register the plugin with Superset
31
const calendarPlugin = new CalendarChartPlugin();
32

33
// The plugin is typically registered with Superset's chart registry
34
// and used through Superset's SuperChart component
35
```
36

37
## Architecture
38

39
The calendar chart plugin is built around several key components:
40

41
- **CalendarChartPlugin**: Main plugin class that integrates with Superset's chart framework
42
- **Calendar Component**: Core D3-based visualization that renders the calendar heatmap  
43
- **ReactCalendar**: React wrapper component with styled theme integration
44
- **Transform Functions**: Data transformation utilities that convert Superset props to chart format
45
- **Control Panel**: Configuration interface for chart customization options
46
- **Utilities**: Helper functions for time formatting and data processing
47

48
## Capabilities
49

50
### Main Plugin Class
51

52
The primary export that registers the calendar chart with Superset's chart framework.
53

54
```javascript { .api }
55
/**
56
 * Main chart plugin class extending Superset's ChartPlugin
57
 */
58
export default class CalendarChartPlugin extends ChartPlugin {
59
  constructor();
60
}
61
```
62

63
### Calendar Visualization Component
64

65
Core visualization function that creates the calendar heatmap using D3 and cal-heatmap library.
66

67
```javascript { .api }
68
/**
69
 * Creates a calendar heatmap visualization in the specified DOM element
70
 * @param {HTMLElement} element - DOM element to render the chart in
71
 * @param {CalendarProps} props - Chart configuration and data properties
72
 */
73
function Calendar(element, props);
74

75
interface CalendarProps {
76
  /** Chart data structure with metrics and timestamps */
77
  data: CalendarData;
78
  /** Chart height in pixels */
79
  height: number;
80
  /** Distance between calendar cells in pixels (default: 3) */
81
  cellPadding?: number;
82
  /** Border radius for calendar cells in pixels (default: 0) */
83
  cellRadius?: number;
84
  /** Size of square calendar cells in pixels (default: 10) */
85
  cellSize?: number;
86
  /** Time granularity for grouping (hour, day, week, month, year) */
87
  domainGranularity: string;
88
  /** Time granularity for individual cells (min, hour, day, week, month) */
89
  subdomainGranularity: string;
90
  /** Color scheme name for visualization */
91
  linearColorScheme: string;
92
  /** Whether to display the color legend */
93
  showLegend: boolean;
94
  /** Whether to display metric names as titles */
95
  showMetricName: boolean;
96
  /** Whether to display values within calendar cells */
97
  showValues: boolean;
98
  /** Number of color intensity steps */
99
  steps: number;
100
  /** Function to format time values for display */
101
  timeFormatter: (timestamp: number) => string;
102
  /** Function to format numeric values for display */
103
  valueFormatter: (value: number) => string;
104
  /** Mapping for verbose metric names */
105
  verboseMap: object;
106
}
107

108
interface CalendarData {
109
  /** Object mapping metric names to timestamp-value pairs */
110
  data: Record<string, Record<string, number>>;
111
  /** Domain granularity setting */
112
  domain: string;
113
  /** Number of time periods to display */
114
  range: number;
115
  /** Start timestamp in milliseconds */
116
  start: number;
117
  /** Subdomain granularity setting */
118
  subdomain: string;
119
}
120
```
121

122
### React Calendar Component
123

124
Styled React wrapper component that integrates with Superset's theming system.
125

126
```jsx { .api }
127
/**
128
 * React wrapper component (internally named 'Calender') for the Calendar visualization with theming
129
 * @param {ReactCalendarProps} props - Component props including className and other properties  
130
 */
131
function ReactCalendar(props);
132

133
interface ReactCalendarProps {
134
  /** CSS class name for styling (required) */
135
  className: string;
136
  /** Additional props passed to underlying Calendar component (default: {}) */
137
  otherProps?: object;
138
}
139
```
140

141
### Data Transformation
142

143
Transforms Superset chart properties into the format expected by the Calendar component.
144

145
```javascript { .api }
146
/**
147
 * Transforms Superset chart props into Calendar component format
148
 * @param {SupersetChartProps} chartProps - Standard Superset chart properties
149
 * @returns {CalendarProps} Transformed properties for Calendar component
150
 */
151
function transformProps(chartProps);
152

153
interface SupersetChartProps {
154
  /** Chart height */
155
  height: number;
156
  /** Form data containing chart configuration */
157
  formData: FormData;
158
  /** Query results data array */
159
  queriesData: array;
160
  /** Datasource metadata with verboseMap */
161
  datasource: object;
162
}
163

164
interface FormData {
165
  /** Cell styling options */
166
  cellPadding: number;
167
  cellRadius: number;
168
  cellSize: number;
169
  /** Time granularity settings (snake_case in form data) */
170
  domainGranularity: string;
171
  subdomainGranularity: string;
172
  /** Visual options */
173
  linearColorScheme: string;
174
  showLegend: boolean;
175
  showMetricName: boolean;
176
  showValues: boolean;
177
  steps: number;
178
  /** Formatting options */
179
  xAxisTimeFormat: string;
180
  yAxisFormat: string;
181
}
182
```
183

184
### Control Panel Configuration
185

186
Configuration schema for the chart's control panel interface in Superset.
187

188
```typescript { .api }
189
/**
190
 * Control panel configuration for chart customization options
191
 */
192
const controlPanel: ControlPanelConfig;
193

194
interface ControlPanelConfig {
195
  /** Array of control panel sections */
196
  controlPanelSections: ControlPanelSection[];
197
  /** Override settings for specific controls */
198
  controlOverrides: Record<string, any>;
199
}
200
```
201

202
### Time Formatting Utilities
203

204
Utility functions for handling time formatting with UTC timezone assumptions.
205

206
```typescript { .api }
207
/**
208
 * Formats timestamp as UTC time string, adjusting for timezone offset
209
 * @param ts - Timestamp to format (number or string)
210
 * @param timeFormat - Optional D3 time format string
211
 * @returns Formatted time string
212
 */
213
export function getFormattedUTCTime(
214
  ts: number | string,
215
  timeFormat?: string
216
): string;
217
```
218

219
## Usage Examples
220

221
### Basic Calendar Chart Setup
222

223
```javascript
224
import CalendarChartPlugin from "@superset-ui/legacy-plugin-chart-calendar";
225

226
// Create and register the plugin
227
const calendarPlugin = new CalendarChartPlugin();
228

229
// Example data format expected by the calendar
230
const sampleData = {
231
  data: {
232
    "page_views": {
233
      "1640995200.0": 150,    // 2022-01-01 values
234
      "1641081600.0": 200,    // 2022-01-02 values
235
      "1641168000.0": 175     // 2022-01-03 values
236
    }
237
  },
238
  domain: "month",
239
  range: 12,
240
  start: 1640995200000,  // Start timestamp in milliseconds
241
  subdomain: "day"
242
};
243
```
244

245
### Custom Time Formatting
246

247
```javascript
248
import { getFormattedUTCTime } from "@superset-ui/legacy-plugin-chart-calendar/lib/utils";
249

250
// Format timestamps for display
251
const timestamp = 1640995200000;
252
const formatted = getFormattedUTCTime(timestamp, "%Y-%m-%d");
253
console.log(formatted); // "2022-01-01"
254

255
// Using different format patterns
256
const timeOnly = getFormattedUTCTime(timestamp, "%H:%M:%S");
257
const fullFormat = getFormattedUTCTime(timestamp, "%B %d, %Y");
258
```
259

260
### Chart Configuration Options
261

262
```javascript
263
// Example configuration for chart customization
264
const chartConfig = {
265
  cellSize: 15,           // Size of calendar cells (default: 10)
266
  cellPadding: 3,         // Space between cells (default: 3 in Calendar, 2 in control panel)
267
  cellRadius: 2,          // Border radius for cells (default: 0)
268
  steps: 5,               // Number of color intensity levels (default: 10)
269
  showLegend: true,       // Display color legend (default: true)
270
  showValues: false,      // Hide values in cells (default: false)
271
  showMetricName: true,   // Show metric name as title (default: true)
272
  domain_granularity: "month",    // Group by months (note: snake_case)
273
  subdomain_granularity: "day",   // Individual cells are days (note: snake_case)
274
  linearColorScheme: "blues"      // Color scheme
275
};
276
```
277

278
## Data Format Requirements
279

280
The calendar chart expects data in a specific nested structure:
281

282
```javascript
283
{
284
  "data": {
285
    "metric_name": {
286
      "timestamp_as_string": numeric_value,
287
      "1640995200.0": 150,
288
      "1641081600.0": 200
289
    }
290
  },
291
  "domain": "month",        // Time grouping level
292
  "range": 12,              // Number of domains to show
293
  "start": 1640995200000,   // Start time in milliseconds
294
  "subdomain": "day"        // Individual cell time unit
295
}
296
```
297

298
## Color Schemes and Styling
299

300
The calendar chart supports Superset's color schemes and integrates with the theming system:
301

302
- Uses sequential color schemes from `@superset-ui/core`
303
- Automatically applies theme colors for tooltips and UI elements
304
- Supports custom CSS styling through className props
305
- Color intensity maps data values to visual representation
306

307
## Error Handling
308

309
The calendar chart includes built-in error handling for:
310

311
- Invalid or missing data structures
312
- Malformed timestamp formats  
313
- Configuration validation errors
314
- DOM rendering failures
315

316
When errors occur, the chart will typically fail gracefully without breaking the parent application.