@xh/hoist 90.0.0 → 90.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (172) hide show
  1. package/CHANGELOG.md +136 -54
  2. package/admin/columns/Tracking.ts +9 -3
  3. package/admin/tabs/activity/tracking/ActivityTrackingModel.ts +155 -47
  4. package/admin/tabs/activity/tracking/ActivityTrackingPanel.ts +25 -4
  5. package/admin/tabs/activity/tracking/chart/AggChartModel.ts +2 -3
  6. package/appcontainer/ImpersonationBarModel.ts +8 -5
  7. package/build/types/admin/tabs/activity/tracking/ActivityTrackingModel.d.ts +25 -5
  8. package/build/types/cmp/cubegrid/CubeGrid.d.ts +26 -0
  9. package/build/types/cmp/cubegrid/CubeGridModel.d.ts +103 -0
  10. package/build/types/cmp/cubegrid/CubeGridPivotModel.d.ts +181 -0
  11. package/build/types/cmp/cubegrid/Types.d.ts +85 -0
  12. package/build/types/cmp/cubegrid/index.d.ts +4 -0
  13. package/build/types/cmp/dataview/DataViewModel.d.ts +6 -10
  14. package/build/types/cmp/grid/GridModel.d.ts +8 -33
  15. package/build/types/cmp/grid/Types.d.ts +51 -1
  16. package/build/types/cmp/grid/columns/Column.d.ts +2 -1
  17. package/build/types/cmp/grid/columns/ColumnGroup.d.ts +6 -0
  18. package/build/types/cmp/grid/helpers/GridCountLabel.d.ts +6 -3
  19. package/build/types/cmp/grid/impl/ColumnWidthCalculator.d.ts +6 -0
  20. package/build/types/cmp/grid/impl/GridLikeModel.d.ts +3 -0
  21. package/build/types/cmp/grid/impl/MenuSupport.d.ts +13 -0
  22. package/build/types/cmp/pdfviewer/PdfViewer.d.ts +14 -0
  23. package/build/types/cmp/pdfviewer/PdfViewerModel.d.ts +150 -0
  24. package/build/types/cmp/pdfviewer/Types.d.ts +55 -0
  25. package/build/types/cmp/pdfviewer/impl/PdfFindInputModel.d.ts +14 -0
  26. package/build/types/cmp/pdfviewer/impl/PdfViewerToolbarModel.d.ts +34 -0
  27. package/build/types/cmp/pdfviewer/impl/ZoomOptions.d.ts +10 -0
  28. package/build/types/cmp/pdfviewer/index.d.ts +3 -0
  29. package/build/types/cmp/statcard/StatCard.d.ts +90 -0
  30. package/build/types/cmp/statcard/index.d.ts +1 -0
  31. package/build/types/cmp/store/StoreFilterField.d.ts +8 -9
  32. package/build/types/cmp/store/impl/StoreFilterFieldImplModel.d.ts +4 -4
  33. package/build/types/cmp/zoneGrid/ZoneGridModel.d.ts +6 -10
  34. package/build/types/core/types/Types.d.ts +6 -0
  35. package/build/types/data/Field.d.ts +8 -1
  36. package/build/types/data/Store.d.ts +12 -0
  37. package/build/types/data/cube/Cube.d.ts +2 -0
  38. package/build/types/data/cube/CubeField.d.ts +3 -2
  39. package/build/types/data/cube/Query.d.ts +66 -4
  40. package/build/types/data/cube/View.d.ts +82 -4
  41. package/build/types/data/cube/ViewRowData.d.ts +13 -0
  42. package/build/types/data/cube/aggregate/MedianAggregator.d.ts +19 -0
  43. package/build/types/data/cube/aggregate/SumIfSameAggregator.d.ts +30 -0
  44. package/build/types/data/cube/impl/RowCache.d.ts +5 -0
  45. package/build/types/data/cube/impl/RowDataGenerator.d.ts +26 -0
  46. package/build/types/data/cube/impl/ViewDiagnostics.d.ts +27 -0
  47. package/build/types/data/cube/pivot/PivotCellRow.d.ts +27 -0
  48. package/build/types/data/cube/pivot/PivotPath.d.ts +45 -0
  49. package/build/types/data/cube/pivot/impl/PivotCells.d.ts +111 -0
  50. package/build/types/data/cube/pivot/impl/PivotReference.d.ts +39 -0
  51. package/build/types/data/cube/pivot/impl/PivotStructure.d.ts +105 -0
  52. package/build/types/data/cube/row/BaseRow.d.ts +12 -0
  53. package/build/types/data/cube/row/LeafRow.d.ts +4 -4
  54. package/build/types/data/cube/row/ParentRow.d.ts +20 -4
  55. package/build/types/data/cube/row/RowUpdate.d.ts +2 -0
  56. package/build/types/data/index.d.ts +3 -0
  57. package/build/types/desktop/cmp/button/grid/ColAutosizeButton.d.ts +6 -3
  58. package/build/types/desktop/cmp/button/grid/ColChooserButton.d.ts +7 -3
  59. package/build/types/desktop/cmp/button/grid/ExpandToLevelButton.d.ts +6 -3
  60. package/build/types/desktop/cmp/button/grid/ExportButton.d.ts +6 -3
  61. package/build/types/desktop/cmp/grid/find/GridFindField.d.ts +8 -9
  62. package/build/types/desktop/cmp/grid/find/impl/GridFindFieldImplModel.d.ts +3 -4
  63. package/build/types/desktop/cmp/pdfviewer/impl/PdfViewerToolbar.d.ts +12 -0
  64. package/build/types/desktop/cmp/statcard/impl/StatCardInfoImpl.d.ts +12 -0
  65. package/build/types/dynamics/desktop.d.ts +2 -0
  66. package/build/types/dynamics/mobile.d.ts +1 -0
  67. package/build/types/icon/Icon.d.ts +12 -0
  68. package/build/types/kit/pdfjs/index.d.ts +23 -0
  69. package/build/types/kit/pdfjs/styles.d.ts +2 -0
  70. package/build/types/kit/swiper/index.d.ts +7 -7
  71. package/build/types/mobile/cmp/button/grid/ColAutosizeButton.d.ts +6 -3
  72. package/build/types/mobile/cmp/button/grid/ColChooserButton.d.ts +6 -3
  73. package/build/types/mobile/cmp/button/grid/ExpandCollapseButton.d.ts +4 -4
  74. package/build/types/mobile/cmp/button/grid/ExpandToLevelButton.d.ts +4 -4
  75. package/build/types/mobile/cmp/pdfviewer/impl/PdfViewerToolbar.d.ts +12 -0
  76. package/cmp/README.md +3 -0
  77. package/cmp/ag-grid/AgGrid.ts +25 -3
  78. package/cmp/cubegrid/CubeGrid.ts +60 -0
  79. package/cmp/cubegrid/CubeGridModel.ts +365 -0
  80. package/cmp/cubegrid/CubeGridPivotModel.ts +943 -0
  81. package/cmp/cubegrid/README.md +343 -0
  82. package/cmp/cubegrid/Types.ts +105 -0
  83. package/cmp/cubegrid/index.ts +10 -0
  84. package/cmp/dataview/DataViewModel.ts +13 -8
  85. package/cmp/grid/Grid.scss +21 -5
  86. package/cmp/grid/GridModel.ts +41 -47
  87. package/cmp/grid/Types.ts +58 -1
  88. package/cmp/grid/columns/Column.ts +3 -1
  89. package/cmp/grid/columns/ColumnGroup.ts +10 -0
  90. package/cmp/grid/helpers/GridCountLabel.ts +12 -5
  91. package/cmp/grid/impl/ColumnGroupHeader.ts +18 -4
  92. package/cmp/grid/impl/ColumnWidthCalculator.ts +24 -0
  93. package/cmp/grid/impl/GridLikeModel.ts +17 -0
  94. package/cmp/grid/impl/MenuSupport.ts +36 -20
  95. package/cmp/pdfviewer/PdfViewer.scss +48 -0
  96. package/cmp/pdfviewer/PdfViewer.ts +102 -0
  97. package/cmp/pdfviewer/PdfViewerModel.ts +641 -0
  98. package/cmp/pdfviewer/README.md +224 -0
  99. package/cmp/pdfviewer/Types.ts +72 -0
  100. package/cmp/pdfviewer/impl/PdfFindInputModel.ts +44 -0
  101. package/cmp/pdfviewer/impl/PdfViewerToolbarModel.ts +45 -0
  102. package/cmp/pdfviewer/impl/ZoomOptions.ts +36 -0
  103. package/cmp/pdfviewer/index.ts +9 -0
  104. package/cmp/statcard/StatCard.scss +181 -0
  105. package/cmp/statcard/StatCard.ts +320 -0
  106. package/cmp/statcard/index.ts +1 -0
  107. package/cmp/store/StoreFilterField.ts +8 -9
  108. package/cmp/store/impl/StoreFilterFieldImplModel.ts +14 -14
  109. package/cmp/zoneGrid/ZoneGridModel.ts +13 -8
  110. package/core/types/Types.ts +7 -0
  111. package/data/Field.ts +10 -0
  112. package/data/Store.ts +25 -2
  113. package/data/cube/Cube.ts +5 -0
  114. package/data/cube/CubeField.ts +5 -0
  115. package/data/cube/Query.ts +170 -17
  116. package/data/cube/README.md +77 -2
  117. package/data/cube/View.ts +211 -32
  118. package/data/cube/ViewRowData.ts +22 -0
  119. package/data/cube/aggregate/MedianAggregator.ts +88 -0
  120. package/data/cube/aggregate/SumIfSameAggregator.ts +128 -0
  121. package/data/cube/impl/RowCache.ts +32 -11
  122. package/data/cube/impl/RowDataGenerator.ts +96 -4
  123. package/data/cube/impl/ViewDiagnostics.ts +47 -0
  124. package/data/cube/pivot/PivotCellRow.ts +73 -0
  125. package/data/cube/pivot/PivotPath.ts +67 -0
  126. package/data/cube/pivot/impl/PivotCells.ts +538 -0
  127. package/data/cube/pivot/impl/PivotReference.ts +125 -0
  128. package/data/cube/pivot/impl/PivotStructure.ts +500 -0
  129. package/data/cube/row/BaseRow.ts +26 -0
  130. package/data/cube/row/LeafRow.ts +9 -8
  131. package/data/cube/row/ParentRow.ts +58 -25
  132. package/data/cube/row/RowUpdate.ts +8 -0
  133. package/data/index.ts +3 -0
  134. package/desktop/appcontainer/AppContainer.ts +5 -1
  135. package/desktop/cmp/button/grid/ColAutosizeButton.ts +21 -5
  136. package/desktop/cmp/button/grid/ColChooserButton.ts +11 -5
  137. package/desktop/cmp/button/grid/ExpandToLevelButton.ts +20 -5
  138. package/desktop/cmp/button/grid/ExportButton.ts +19 -7
  139. package/desktop/cmp/dash/canvas/DashCanvas.ts +26 -2
  140. package/desktop/cmp/grid/find/GridFindField.ts +8 -9
  141. package/desktop/cmp/grid/find/impl/GridFindFieldImplModel.ts +15 -16
  142. package/desktop/cmp/grid/impl/colchooser/ColChooserBucketModel.ts +1 -1
  143. package/desktop/cmp/pdfviewer/impl/PdfViewerToolbar.ts +190 -0
  144. package/desktop/cmp/statcard/impl/StatCardInfoImpl.ts +27 -0
  145. package/docs/README.md +6 -2
  146. package/docs/doc-registry.json +21 -5
  147. package/docs/upgrade-notes/v90-upgrade-notes.md +130 -0
  148. package/docs/version-compatibility.md +2 -1
  149. package/dynamics/desktop.ts +4 -0
  150. package/dynamics/mobile.ts +2 -0
  151. package/format/FormatNumber.ts +6 -2
  152. package/icon/Icon.ts +18 -0
  153. package/icon/index.ts +32 -0
  154. package/kit/README.md +2 -0
  155. package/kit/pdfjs/PdfJs.scss +25 -0
  156. package/kit/pdfjs/index.ts +103 -0
  157. package/kit/pdfjs/pdf_viewer.css +6481 -0
  158. package/kit/pdfjs/styles.ts +12 -0
  159. package/mcp/README.md +13 -0
  160. package/mcp/data/import-paths.ts +4 -8
  161. package/mcp/data/index-cache.ts +2 -1
  162. package/mcp/data/ts-registry.ts +8 -29
  163. package/mcp/util/paths.ts +26 -0
  164. package/mobile/appcontainer/AppContainer.ts +3 -1
  165. package/mobile/cmp/button/grid/ColAutosizeButton.ts +20 -5
  166. package/mobile/cmp/button/grid/ColChooserButton.ts +12 -5
  167. package/mobile/cmp/button/grid/ExpandCollapseButton.ts +10 -6
  168. package/mobile/cmp/button/grid/ExpandToLevelButton.ts +10 -6
  169. package/mobile/cmp/pdfviewer/impl/PdfViewerToolbar.ts +137 -0
  170. package/package.json +14 -8
  171. package/public/msal-redirect-bridge.min.js +1 -1
  172. package/styles/vars.scss +59 -0
@@ -14,9 +14,9 @@ import type {
14
14
  OmitFn,
15
15
  StoreRecord
16
16
  } from '@xh/hoist/data';
17
- import {parseFilter} from '@xh/hoist/data';
17
+ import {appendFilter, parseFilter} from '@xh/hoist/data';
18
18
  import {throwIf} from '@xh/hoist/utils/js';
19
- import {find, isEqual, sortBy, uniq} from 'lodash';
19
+ import {compact, find, isEmpty, isEqual, sortBy, uniq} from 'lodash';
20
20
  import type {Cube} from './Cube';
21
21
  import {CubeField} from './CubeField';
22
22
 
@@ -26,7 +26,8 @@ import {CubeField} from './CubeField';
26
26
  *
27
27
  * Key options beyond `dimensions` and `filter`: `includeRoot` adds a grand-total row,
28
28
  * `includeLeaves` exposes source records as tree children, and `provideLeaves` makes them
29
- * accessible programmatically without rendering in the tree.
29
+ * accessible programmatically without rendering in the tree. `pivot` additionally slices the
30
+ * aggregates across a second axis of dimensions - see {@link PivotSpec}.
30
31
  *
31
32
  * See the Cube package README (`data/cube/README.md#querying-with-views`) for query patterns.
32
33
  *
@@ -42,7 +43,8 @@ export interface QueryConfig {
42
43
 
43
44
  /**
44
45
  * Fields or field names. If unspecified will include all available {@link Cube.fields}.
45
- * Specify a subset to optimize aggregation performance.
46
+ * Specify a subset to optimize aggregation performance. `dimensions` and any `pivot` fields
47
+ * are always included.
46
48
  */
47
49
  fields?: string[] | CubeField[];
48
50
 
@@ -128,6 +130,56 @@ export interface QueryConfig {
128
130
  * Return true to omit the row. Defaults to Cube.omitFn.
129
131
  */
130
132
  omitFn?: OmitFn;
133
+
134
+ /**
135
+ * Pivot additional dimensions into *columns* rather than rows, aggregating measures at each
136
+ * intersection. Omit for an ordinary view - see {@link PivotSpec}.
137
+ */
138
+ pivot?: PivotSpec;
139
+ }
140
+
141
+ /**
142
+ * Pivot axis of a {@link QueryConfig} - extra dimensions sliced into columns rather than rows, and
143
+ * the measures aggregated at each intersection. `QueryConfig.dimensions` keeps its meaning as the
144
+ * row hierarchy; the two axes are orthogonal. Results carry the structure as
145
+ * {@link ViewResult.paths} and {@link ViewResult.cellFields}, with each cell value published as a
146
+ * synthetic field on its group row - see `CubeGridModel` for rendering.
147
+ */
148
+ export interface PivotSpec {
149
+ /**
150
+ * Pivot dimensions, outermost first. 1 is typical, 3 the practical ceiling. Empty to degenerate
151
+ * to plain View behavior, so apps can toggle pivoting without swapping view objects.
152
+ */
153
+ dimensions: string[] | CubeField[];
154
+
155
+ /**
156
+ * Measures to aggregate per cell - fields with an aggregator, and not `isDimension`. Added to
157
+ * the query's `fields` along with any {@link Aggregator.dependsOn}. Empty degenerates to plain
158
+ * View behavior, as for `dimensions`.
159
+ */
160
+ measures: string[] | CubeField[];
161
+
162
+ /**
163
+ * True to exclude records with a null / blank pivot dimension value entirely, via an implicit
164
+ * filter, so they leave the group aggregates too and a row's summary covers the same records
165
+ * as its cells. Default false, which gives such records their own empty path.
166
+ */
167
+ excludeEmptyPivotValues?: boolean;
168
+
169
+ /**
170
+ * Decline the result if the discovered pivot path count exceeds this - see
171
+ * {@link ViewResult.exception}. Default 100; null to disable.
172
+ */
173
+ maxPivotPaths?: number;
174
+ }
175
+
176
+ /** Resolved form of a {@link PivotSpec}, as held by a {@link Query}. */
177
+ export interface Pivot {
178
+ dimensions: CubeField[];
179
+ dimensionNames: string[];
180
+ measures: CubeField[];
181
+ excludeEmptyPivotValues: boolean;
182
+ maxPivotPaths: number;
131
183
  }
132
184
 
133
185
  /**
@@ -137,7 +189,8 @@ export interface QueryConfig {
137
189
  */
138
190
  export class Query {
139
191
  /**
140
- * Queried fields, sorted by name. Includes `dimensions`, added here if not already present.
192
+ * Queried fields, sorted by name. Includes `dimensions` and pivot fields, added here if not
193
+ * already present.
141
194
  */
142
195
  readonly fields: CubeField[];
143
196
  readonly dimensions: CubeField[];
@@ -151,8 +204,12 @@ export class Query {
151
204
  readonly lockFn: LockFn;
152
205
  readonly bucketSpecFn: BucketSpecFn;
153
206
  readonly omitFn: OmitFn;
207
+ /** Resolved pivot spec, or null for an ordinary query. */
208
+ readonly pivot: Pivot;
154
209
 
210
+ // Pre-derivation inputs, so `clone` re-derives from these rather than compounding.
155
211
  private readonly _rawFields: string[] | CubeField[];
212
+ private readonly _rawFilter: Filter;
156
213
  private readonly _testFn: FilterTestFn;
157
214
 
158
215
  constructor({
@@ -166,34 +223,39 @@ export class Query {
166
223
  omitRedundantNodes = true,
167
224
  lockFn = cube.lockFn,
168
225
  bucketSpecFn = cube.bucketSpecFn,
169
- omitFn = cube.omitFn
226
+ omitFn = cube.omitFn,
227
+ pivot = null
170
228
  }: QueryConfig) {
171
229
  this.cube = cube;
172
230
  this._rawFields = fields?.slice();
231
+ this._rawFilter = parseFilter(filter);
173
232
  this.dimensions = this.parseDimensions(dimensions);
233
+ this.pivot = this.parsePivot(pivot);
174
234
  // Ensure canonical field order so equivalent queries compare equal
175
235
  this.fields = sortBy(
176
- uniq([...this.parseFields(fields), ...(this.dimensions ?? [])]),
236
+ uniq([...this.parseFields(fields), ...(this.dimensions ?? []), ...this.pivotFields()]),
177
237
  'name'
178
238
  );
179
239
  this.includeRoot = includeRoot;
180
240
  this.includeLeaves = includeLeaves;
181
241
  this.provideLeaves = provideLeaves;
182
242
  this.omitRedundantNodes = omitRedundantNodes;
183
- this.filter = parseFilter(filter);
243
+ this.filter = this.applyPivotFilter(this._rawFilter);
184
244
  this.lockFn = lockFn;
185
245
  this.bucketSpecFn = bucketSpecFn;
186
246
  this.omitFn = omitFn;
187
247
 
188
248
  this._testFn = this.filter?.getTestFn(this.cube.store) ?? null;
189
249
  this.hasFilter = this._testFn != null;
250
+
251
+ this.validatePivot();
190
252
  }
191
253
 
192
- clone(overrides: Partial<QueryConfig>) {
193
- const conf = {
254
+ clone(overrides: Partial<QueryConfig>): Query {
255
+ return new Query({
194
256
  dimensions: this.dimensions,
195
257
  fields: this._rawFields, // NOT this.fields - would retain stale dimensions
196
- filter: this.filter,
258
+ filter: this._rawFilter, // NOT this.filter - would re-append any pivot exclusion
197
259
  includeRoot: this.includeRoot,
198
260
  includeLeaves: this.includeLeaves,
199
261
  provideLeaves: this.provideLeaves,
@@ -201,11 +263,10 @@ export class Query {
201
263
  lockFn: this.lockFn,
202
264
  bucketSpecFn: this.bucketSpecFn,
203
265
  omitFn: this.omitFn,
266
+ pivot: this.pivot,
204
267
  cube: this.cube,
205
268
  ...overrides
206
- };
207
-
208
- return new Query(conf);
269
+ });
209
270
  }
210
271
 
211
272
  test(record: StoreRecord): boolean {
@@ -230,6 +291,7 @@ export class Query {
230
291
  return (
231
292
  isEqual(this.fields, other.fields) &&
232
293
  isEqual(this.dimensions, other.dimensions) &&
294
+ isEqual(this.pivot, other.pivot) &&
233
295
  this.cube === other.cube &&
234
296
  this.includeRoot === other.includeRoot &&
235
297
  this.includeLeaves === other.includeLeaves &&
@@ -254,10 +316,10 @@ export class Query {
254
316
 
255
317
  private parseDimensions(raw: CubeField[] | string[]): CubeField[] {
256
318
  if (!raw) return null;
257
- if (raw[0] instanceof CubeField) return raw.slice() as CubeField[]; // force clone, we retain.
258
319
  const {fields} = this.cube;
259
- return raw.map(name => {
260
- const field = find(fields, {name});
320
+ return (raw as Array<CubeField | string>).map(it => {
321
+ const name = it instanceof CubeField ? it.name : it,
322
+ field = it instanceof CubeField ? it : find(fields, {name});
261
323
  throwIf(
262
324
  !field?.isDimension,
263
325
  `Dimension '${name}' is not a Field on this Cube, or is not specified with isDimension:true.`
@@ -265,4 +327,95 @@ export class Query {
265
327
  return field;
266
328
  });
267
329
  }
330
+
331
+ //------------------------
332
+ // Pivot
333
+ //------------------------
334
+ /** True if this query pivots on at least one dimension and measure. */
335
+ get isPivoted(): boolean {
336
+ return !isEmpty(this.pivot?.dimensions) && !isEmpty(this.pivot.measures);
337
+ }
338
+
339
+ private parsePivot(spec: PivotSpec): Pivot {
340
+ if (!spec) return null;
341
+
342
+ const {dimensions, measures, excludeEmptyPivotValues = false, maxPivotPaths = 100} = spec,
343
+ dims = this.parseDimensions(dimensions) ?? [];
344
+
345
+ return {
346
+ dimensions: dims,
347
+ dimensionNames: dims.map(it => it.name),
348
+ measures: this.parseMeasures(measures),
349
+ excludeEmptyPivotValues,
350
+ maxPivotPaths
351
+ };
352
+ }
353
+
354
+ private parseMeasures(raw: CubeField[] | string[]): CubeField[] {
355
+ if (!raw) return [];
356
+ const {fields} = this.cube;
357
+ return (raw as Array<CubeField | string>).map(it => {
358
+ const name = it instanceof CubeField ? it.name : it,
359
+ field = it instanceof CubeField ? it : find(fields, {name});
360
+ throwIf(!field, `Measure '${name}' is not a Field on this Cube.`);
361
+ return field;
362
+ });
363
+ }
364
+
365
+ /** The pivot's own fields plus anything their aggregators read - always queried. */
366
+ private pivotFields(): CubeField[] {
367
+ const {pivot, cube} = this;
368
+ if (!pivot) return [];
369
+
370
+ const deps = pivot.measures.flatMap(f => f.aggregator?.dependsOn ?? []);
371
+ return [
372
+ ...pivot.dimensions,
373
+ ...pivot.measures,
374
+ ...compact(deps.map(n => cube.getField(n)))
375
+ ];
376
+ }
377
+
378
+ /**
379
+ * Fold `excludeEmptyPivotValues` into the query filter as FieldFilters - a `FunctionFilter`
380
+ * compares its `testFn` by reference, which would defeat `View.updateQuery`'s equality check.
381
+ */
382
+ private applyPivotFilter(filter: Filter): Filter {
383
+ const {pivot} = this;
384
+ if (!pivot?.excludeEmptyPivotValues || !this.isPivoted) return filter;
385
+
386
+ const excludes = pivot.dimensionNames.map(field => ({
387
+ field,
388
+ op: '!=' as const,
389
+ value: [null]
390
+ }));
391
+ return appendFilter(filter, ...excludes);
392
+ }
393
+
394
+ private validatePivot() {
395
+ const {pivot} = this;
396
+ if (!pivot) return;
397
+
398
+ const dimNames = (this.dimensions ?? []).map(it => it.name);
399
+
400
+ // A measure is never a dimension, so its bare name - the root path's cell field - is never
401
+ // also written by a grouping dimension.
402
+ pivot.measures.forEach(({name, aggregator, isDimension}) => {
403
+ throwIf(!aggregator, `Pivot measure '${name}' must specify an aggregator.`);
404
+ throwIf(isDimension, `Pivot measure '${name}' must not be a dimension.`);
405
+ });
406
+
407
+ const overlap = pivot.dimensionNames.filter(it => dimNames.includes(it));
408
+ throwIf(
409
+ !isEmpty(overlap),
410
+ `Field(s) '${overlap}' cannot be both a grouping and a pivot dimension.`
411
+ );
412
+
413
+ // A group node must decompose on one axis - bucketing leaves would double count on the
414
+ // pivot axis. See `PivotStructure`.
415
+ throwIf(
416
+ this.isPivoted && this.bucketSpecFn && this.includeLeaves,
417
+ 'Pivoting is not supported alongside `bucketSpecFn` with `includeLeaves` - bucketing ' +
418
+ 'leaves would give a pivot cell two update routes into the same parent.'
419
+ );
420
+ }
268
421
  }
@@ -74,15 +74,20 @@ const cube = new Cube({
74
74
  | `'AVG_STRICT'` | Average only if all non-null |
75
75
  | `'MIN'` | Minimum value |
76
76
  | `'MAX'` | Maximum value |
77
- | `'UNIQUE'` | Count of unique values |
77
+ | `'MEDIAN'` | Median of non-null values over all leaves |
78
+ | `'UNIQUE'` | The value shared by all children, or null if they differ |
79
+ | `'SINGLE'` | The value of the only child, or null if there is more than one |
80
+ | `'NULL'` | Always null - for fields that should not be aggregated |
78
81
  | `'LEAF_COUNT'` | Count of leaf records |
79
82
  | `'CHILD_COUNT'` | Count of immediate children |
80
83
  | `WeightedAverageAggregator` | Average weighted by a second field, e.g. price by quantity |
84
+ | `SumIfSameAggregator` | Total only if all leaves with a value share a second field, such as a currency |
81
85
 
82
86
  `WeightedAverageAggregator` takes the name of its weight field, so is instantiated per field rather
83
87
  than aliased by token: `{name: 'price', aggregator: new WeightedAverageAggregator('qty')}`. It
84
88
  reads the weight from each leaf's source record, so the weight field need not be queried, and
85
- updates incrementally on a change to either field.
89
+ updates incrementally on a change to either field. `SumIfSameAggregator` takes the name of the
90
+ field its leaves must share in the same way: `new SumIfSameAggregator('currency')`.
86
91
 
87
92
  A field is never aggregated at or below the level at which it is applied as a dimension - rows
88
93
  there publish the dimension value, and rows above aggregate over those values, one per grouped row.
@@ -260,6 +265,75 @@ const grandTotal = rows.find(r => r.isRoot);
260
265
  Use `createView()` when you need connected auto-updates or store integration;
261
266
  use `executeQuery()` for lightweight, fire-and-forget queries.
262
267
 
268
+ ## Pivoting with `pivot`
269
+
270
+ A query can slice its aggregates across a second axis of dimensions, so a measure appears once per
271
+ value of a *pivot* dimension - the classic region-by-sector table. Set `QueryConfig.pivot`:
272
+
273
+ ```typescript
274
+ const view = cube.createView({
275
+ query: {
276
+ dimensions: ['fund', 'trader'], // Row hierarchy, as usual
277
+ includeRoot: true,
278
+ pivot: {
279
+ dimensions: ['region'], // Columns - 1 is typical, 3 the ceiling
280
+ measures: ['mktVal', 'pnl'] // Measures aggregated per cell
281
+ }
282
+ },
283
+ connect: true
284
+ });
285
+ ```
286
+
287
+ `dimensions` keeps its meaning as the row hierarchy; the two axes are orthogonal. Pivot dimensions
288
+ are fields with `isDimension: true`, and measures are fields with an aggregator that are not -
289
+ `Cube.dimensions` and `Cube.measures` list them. See `PivotSpec` for the remaining options -
290
+ excluding records with a blank pivot value entirely, and a cap on the number of paths.
291
+
292
+ **What the result carries.** Every group row still holds its normal aggregates. In addition, each
293
+ cell is written onto the row as a synthetic field named `{path}>>{measure}`:
294
+
295
+ ```typescript
296
+ view.result.rows[0].children[0];
297
+ // {cubeLabel: 'Fund A', mktVal: 42, pnl: 7, <- the row summaries, as without a pivot
298
+ // 'US>>mktVal': 30, 'US>>pnl': 5, <- cells for the US path
299
+ // 'EU>>mktVal': 12, 'EU>>pnl': 2} <- cells for the EU path
300
+
301
+ view.result.paths; // PivotPath tree - US, EU, each with `children` for deeper dimensions
302
+ view.result.cellFields; // One {name, path, measure} per cell field, including the row summaries
303
+ ```
304
+
305
+ A row's summary aggregates the same records as its top-level cells, so for an additive measure it
306
+ equals their sum. Cells are sparse: a (row, path) pair with no records beneath it has no field at
307
+ all, and a blank pivot value forms its own path, with `isEmpty` set and a null `value`, unless
308
+ `excludeEmptyPivotValues` drops those records - from the row summaries too. `paths` and
309
+ `cellFields` keep their identity while the pivot structure is unchanged, so a consumer can track
310
+ them to decide when to rebuild columns, which is what `CubeGridModel` does.
311
+
312
+ **Loading a store.** Cell fields are discovered from the data, so a connected Store has to learn
313
+ them as paths come and go. `CubeGridModel` handles this for its own Store; read `result` directly
314
+ to consume a pivoted View without a grid.
315
+
316
+ **Updates.** A pivoted View ticks like any other: a value change adjusts the affected cells and
317
+ totals in place, while a record moving between pivot paths rebuilds, the same as a change to a row
318
+ dimension. `updateQuery` with a different `pivot.dimensions` or `measures` reshapes the columns;
319
+ an empty `pivot.dimensions` or `measures` degenerates to an ordinary View so an app can toggle
320
+ pivoting without swapping objects.
321
+
322
+ **How it works, briefly.** Each group row carries a hidden subtree of cell rows, one per populated
323
+ pivot path. They are real rows in the aggregation network, so every aggregator - built-in or
324
+ custom - works on them unchanged, and a leaf propagates each tick up both its group parent and its
325
+ cell. Cost scales with populated cells, not rows times paths. The planner behind this is
326
+ `PivotStructure` in `data/cube/pivot/impl`, with its correctness properties pinned by its spec.
327
+
328
+ **Limits.** Pivoting is not supported together with `bucketSpecFn` and `includeLeaves`, and a
329
+ dimension cannot appear on both axes. `maxPivotPaths` (default 100) declines the result when a
330
+ pivot dimension is wider than intended: the View publishes the reason as `ViewResult.exception`
331
+ and empties its rows and stores, and a `CubeGrid` renders an `ErrorMessage` in its place. Pick a
332
+ lower-cardinality dimension or raise the cap deliberately. Any routine `HoistException` thrown in
333
+ the View's pipeline, such as from an app aggregator, is handled the same way.
334
+
335
+ To render a View, pivoted or not, see [`/cmp/cubegrid/`](../../cmp/cubegrid/README.md).
336
+
263
337
  ## Accessing View Data
264
338
 
265
339
  There are two ways to consume View results:
@@ -316,4 +390,5 @@ records from `cube.store` directly if you need them.
316
390
 
317
391
  - [`/data/`](../README.md) - Store, Field, Filter, Validation - the core data layer
318
392
  - [`/cmp/grid/`](../../cmp/grid/README.md) - GridModel consumes Store for data display
393
+ - [`/cmp/cubegrid/`](../../cmp/cubegrid/README.md) - CubeGrid renders a View as a grid, pivoted or not
319
394
  - `/cmp/grouping/` - GroupingChooser for specifying multi-level dimension groupings