0
# Internal Architecture Details
1

2
This document describes the internal implementation architecture of the pivot table plugin. These components are **internal implementation details** and are not part of the public API of `@superset-ui/plugin-chart-pivot-table`.
3

4
**Important:** The components described here should not be imported or used directly. All functionality is available through the public `PivotTableChartPlugin` API.
5

6
## Capabilities
7

8
### PivotTable Component
9

10
Core pivot table rendering component from the internal react-pivottable library.
11

12
```typescript { .api }
13
/**
14
 * Internal pivot table rendering component
15
 * Handles the actual pivot table display and interaction
16
 * Note: This is an internal component, not exported from the public API
17
 */
18
// Internal: PivotTable component from react-pivottable library
19
```
20

21
### Aggregation Templates
22

23
Comprehensive set of built-in aggregation functions for data summarization.
24

25
```typescript { .api }
26
/**
27
 * Internal collection of aggregation function templates
28
 * Each template returns a configured aggregation function
29
 * Note: This is internal to the plugin, not exported from the public API
30
 */
31
// Internal: aggregatorTemplates from react-pivottable utilities
32

33
interface AggregatorTemplates {
34
  /** Count of non-null values */
35
  count: (formatter: NumberFormatter) => AggregatorFunction;
36
  /** Count of unique values */
37
  countUnique: (formatter: NumberFormatter) => AggregatorFunction;
38
  /** List unique values separated by delimiter */
39
  listUnique: (separator: string, formatter: NumberFormatter) => AggregatorFunction;
40
  /** Sum of numeric values */
41
  sum: (formatter: NumberFormatter) => AggregatorFunction;
42
  /** Average of numeric values */
43
  average: (formatter: NumberFormatter) => AggregatorFunction;
44
  /** Median of numeric values */
45
  median: (formatter: NumberFormatter) => AggregatorFunction;
46
  /** Sample variance calculation */
47
  var: (ddof: number, formatter: NumberFormatter) => AggregatorFunction;
48
  /** Sample standard deviation calculation */
49
  stdev: (ddof: number, formatter: NumberFormatter) => AggregatorFunction;
50
  /** Minimum value */
51
  min: (formatter: NumberFormatter) => AggregatorFunction;
52
  /** Maximum value */
53
  max: (formatter: NumberFormatter) => AggregatorFunction;
54
  /** First non-null value */
55
  first: (formatter: NumberFormatter) => AggregatorFunction;
56
  /** Last non-null value */ 
57
  last: (formatter: NumberFormatter) => AggregatorFunction;
58
  /** Fraction calculations relative to total, row, or column */
59
  fractionOf: (
60
    numeratorAgg: AggregatorFunction,
61
    denominatorType: 'total' | 'row' | 'col',
62
    formatter: NumberFormatter
63
  ) => AggregatorFunction;
64
}
65
```
66

67
**Usage Example:**
68

69
```typescript
70
import { aggregatorTemplates } from "@superset-ui/plugin-chart-pivot-table/src/react-pivottable";
71
import { getNumberFormatter } from "@superset-ui/core";
72

73
const formatter = getNumberFormatter('.2f');
74

75
// Create specific aggregation functions
76
const aggregators = {
77
  'Count': aggregatorTemplates.count(formatter),
78
  'Sum': aggregatorTemplates.sum(formatter),
79
  'Average': aggregatorTemplates.average(formatter),
80
  'Sum as % of Total': aggregatorTemplates.fractionOf(
81
    aggregatorTemplates.sum(),
82
    'total',
83
    formatter
84
  ),
85
};
86
```
87

88
### Sorting Utilities
89

90
Utility functions for data sorting within the pivot table.
91

92
```typescript { .api }
93
/**
94
 * Sorting utility function
95
 * Provides natural sorting for pivot table data
96
 */
97
export const sortAs: SortFunction;
98

99
type SortFunction = (order: string[]) => (a: string, b: string) => number;
100
```
101

102
**Usage Example:**
103

104
```typescript
105
import { sortAs } from "@superset-ui/plugin-chart-pivot-table/src/react-pivottable";
106

107
// Create custom sort order
108
const customSort = sortAs(['High', 'Medium', 'Low']);
109
const sortedData = data.sort((a, b) => customSort(a.priority, b.priority));
110
```
111

112
### Built-in Aggregation Functions
113

114
The pivot table engine provides a comprehensive factory for creating aggregation functions.
115

116
```typescript { .api }
117
/**
118
 * Factory function that creates all available aggregation functions
119
 * @param formatter - Number formatter for displaying aggregated values
120
 * @returns Object containing all aggregation functions
121
 */
122
const aggregatorsFactory = (formatter: NumberFormatter) => ({
123
  /** Count of non-null values */
124
  'Count': AggregatorFunction;
125
  /** Count of unique values */
126
  'Count Unique Values': AggregatorFunction;
127
  /** List unique values with comma separation */
128
  'List Unique Values': AggregatorFunction;
129
  /** Sum of numeric values */
130
  'Sum': AggregatorFunction;
131
  /** Average of numeric values */
132
  'Average': AggregatorFunction;
133
  /** Median of numeric values */
134
  'Median': AggregatorFunction;
135
  /** Sample variance */
136
  'Sample Variance': AggregatorFunction;
137
  /** Sample standard deviation */
138
  'Sample Standard Deviation': AggregatorFunction;
139
  /** Minimum value */
140
  'Minimum': AggregatorFunction;
141
  /** Maximum value */
142
  'Maximum': AggregatorFunction;
143
  /** First non-null value */
144
  'First': AggregatorFunction;
145
  /** Last non-null value */
146
  'Last': AggregatorFunction;
147
  /** Sum as fraction of total */
148
  'Sum as Fraction of Total': AggregatorFunction;
149
  /** Sum as fraction of row total */
150
  'Sum as Fraction of Rows': AggregatorFunction;
151
  /** Sum as fraction of column total */
152
  'Sum as Fraction of Columns': AggregatorFunction;
153
  /** Count as fraction of total */
154
  'Count as Fraction of Total': AggregatorFunction;
155
  /** Count as fraction of row total */
156
  'Count as Fraction of Rows': AggregatorFunction;
157
  /** Count as fraction of column total */
158
  'Count as Fraction of Columns': AggregatorFunction;
159
});
160
```
161

162
### AggregatorFunction Type
163

164
Type definition for aggregation functions used in the pivot table.
165

166
```typescript { .api }
167
type AggregatorFunction = {
168
  /** Function to process and aggregate data values */
169
  (data: DataRecord[], rowKey: string[], colKey: string[]): {
170
    /** Aggregated numeric value */
171
    value: number;
172
    /** Formatted display string */
173
    format: (value: number) => string;
174
  };
175
};
176
```
177

178
### NumberFormatter Type
179

180
Number formatting interface for displaying aggregated values.
181

182
```typescript { .api }
183
interface NumberFormatter {
184
  /** Format a number for display */
185
  (value: number): string;
186
  /** Formatter ID */
187
  id: string;
188
}
189
```
190

191
### Advanced Aggregation Usage
192

193
**Custom Aggregation Configuration:**
194

195
```typescript
196
import { 
197
  aggregatorTemplates, 
198
  PivotTable 
199
} from "@superset-ui/plugin-chart-pivot-table/src/react-pivottable";
200
import { getNumberFormatter } from "@superset-ui/core";
201

202
const percentFormatter = getNumberFormatter('.1%');
203
const currencyFormatter = getNumberFormatter('$,.2f');
204

205
// Configure pivot table with custom aggregations
206
const pivotConfig = {
207
  data: salesData,
208
  rows: ['region'],
209
  cols: ['quarter'],
210
  aggregatorName: 'Sum',
211
  aggregators: {
212
    'Sum': aggregatorTemplates.sum(currencyFormatter),
213
    'Average': aggregatorTemplates.average(currencyFormatter),
214
    '% of Total': aggregatorTemplates.fractionOf(
215
      aggregatorTemplates.sum(),
216
      'total',
217
      percentFormatter
218
    ),
219
  },
220
  vals: ['amount']
221
};
222
```
223

224
### Table Renderers
225

226
The engine supports various table rendering modes for different display requirements.
227

228
```typescript { .api }
229
interface TableRenderer {
230
  /** Standard table renderer */
231
  'Table': ReactComponent;
232
  /** Table with bars for visual representation */
233
  'Table Barchart': ReactComponent;
234
  /** Heatmap table renderer */
235
  'Table Heatmap': ReactComponent;
236
  /** Row heatmap renderer */
237
  'Table Row Heatmap': ReactComponent;
238
  /** Column heatmap renderer */
239
  'Table Col Heatmap': ReactComponent;
240
}
241
```