@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
@@ -0,0 +1,538 @@
1
+ /*
2
+ * This file belongs to Hoist, an application development toolkit
3
+ * developed by Extremely Heavy Industries (www.xh.io | info@xh.io)
4
+ *
5
+ * Copyright © 2026 Extremely Heavy Industries Inc.
6
+ */
7
+
8
+ import type {PlainObject} from '@xh/hoist/core';
9
+ import type {Store, StoreRecord} from '@xh/hoist/data';
10
+ import {Field} from '@xh/hoist/data';
11
+ import {throwIf} from '@xh/hoist/utils/js';
12
+ import {isEmpty} from 'lodash';
13
+ import type {CubeField} from '../../CubeField';
14
+ import type {PivotCellField} from '../PivotPath';
15
+ import {PivotPath} from '../PivotPath';
16
+ import {BaseRow} from '../../row/BaseRow';
17
+ import type {LeafRow} from '../../row/LeafRow';
18
+ import {PivotCellRow} from '../PivotCellRow';
19
+ import type {View} from '../../View';
20
+ import type {ViewRowData} from '../../ViewRowData';
21
+ import {
22
+ buildPivotStructure,
23
+ CHILD_KIND_LEAF,
24
+ discoverPivotPaths,
25
+ pivotCellFieldName,
26
+ type PivotStructure,
27
+ type PivotPathDiscoveryResult,
28
+ type PivotPathSpec
29
+ } from './PivotStructure';
30
+ import type {PivotPhases} from '../../impl/ViewDiagnostics';
31
+
32
+ /**
33
+ * Pivot support for a {@link View} whose query sets {@link QueryConfig.pivot}.
34
+ *
35
+ * Every node of the row hierarchy carries its own subtree of {@link PivotCellRow}s, one per
36
+ * populated pivot path. Cells are real rows in the aggregation network - aggregators work
37
+ * unmodified and ticks propagate incrementally - but never enter the visible tree or reach a
38
+ * Store. Each cell's values are written onto its owning group row as flat synthetic fields, named
39
+ * per {@link ViewResult.cellFields}, so they behave as ordinary Store fields.
40
+ *
41
+ * Created on a View's first pivoted query and retained; holds no cells under an unpivoted query.
42
+ * `PivotStructure` plans the cells, this class materializes them.
43
+ *
44
+ * @internal
45
+ */
46
+ export class PivotCells {
47
+ private readonly view: View;
48
+
49
+ /** Pivot path tree, top-level paths first - see {@link ViewResult.paths}. */
50
+ paths: PivotPath[] = [];
51
+ /** One entry per (path, measure) - see {@link ViewResult.cellFields}. */
52
+ cellFields: PivotCellField[] = [];
53
+ /** Index of each path within `allPaths` - what an exposed leaf's `_pivotPathIdx` names. */
54
+ pathIdx: Map<PivotPath, number> = new Map();
55
+ /** Index of each path's parent within `allPaths`, -1 for the root, by path index. */
56
+ pathParentIdx: Int32Array = new Int32Array(0);
57
+
58
+ // Aggregation field lists for cell rows - the measures plus their dependencies.
59
+ cellAggFields: CubeField[] = [];
60
+ cellAggFieldNames: Set<string> = new Set();
61
+ cellCanAggregateFnFields: CubeField[] = [];
62
+ cellComplexAggFields: CubeField[] = [];
63
+
64
+ private allPaths: PivotPath[] = [];
65
+ private pathKeys: string[] = null;
66
+ private measureNames: string[] = [];
67
+ /** Keyed on path identity. */
68
+ private cellFieldNamesByPath: Map<PivotPath, string[]> = new Map();
69
+ /** This generation's path discovery - see `discoverPaths`. */
70
+ private discovery: PivotPathDiscoveryResult = null;
71
+ private cellRows: PivotCellRow[] = [];
72
+ /** Phase timings for the generation in progress, reported by `generateCells`. */
73
+ private phases: PivotPhases = null;
74
+ /** Cell fields last declared on each store, by identity - the structural-change signal. */
75
+ private syncedCellFields = new WeakMap<Store, PivotCellField[]>();
76
+
77
+ constructor(view: View) {
78
+ this.view = view;
79
+ }
80
+
81
+ //------------------------
82
+ // View lifecycle
83
+ //------------------------
84
+ /** Derive the cell aggregation field lists. Runs with the View's own `buildIndices`. */
85
+ buildIndices() {
86
+ const {view} = this,
87
+ names = new Set<string>();
88
+ this.measures.forEach(f => {
89
+ names.add(f.name);
90
+ f.aggregator?.dependsOn?.forEach(n => names.add(n));
91
+ });
92
+
93
+ const fields: CubeField[] = [];
94
+ names.forEach(name => {
95
+ const field = view.getField(name);
96
+ if (field?.aggregator) fields.push(field);
97
+ });
98
+ this.cellAggFields = fields;
99
+ this.cellAggFieldNames = new Set(fields.map(f => f.name));
100
+ this.cellCanAggregateFnFields = fields.filter(f => f.canAggregateFn);
101
+ this.cellComplexAggFields = fields.filter(f => !f.aggregator.dependsOnChildrenOnly);
102
+
103
+ view._rowDataGenerator.onCellAggFieldsChange();
104
+ }
105
+
106
+ /**
107
+ * Discover the pivot path tree and publish the cell fields it implies. Runs before row
108
+ * generation, as the exposed-leaf class is built from the cell fields and leaves are minted
109
+ * during that pass.
110
+ */
111
+ discoverPaths() {
112
+ const {view} = this,
113
+ {query} = view,
114
+ start = performance.now();
115
+
116
+ if (query.isPivoted) {
117
+ const {pivot} = query;
118
+ this.discovery = discoverPivotPaths(view._records.list, pivot.dimensionNames, {
119
+ maxPivotPaths: pivot.maxPivotPaths
120
+ });
121
+ this.syncPaths(this.discovery.paths);
122
+ } else {
123
+ this.discovery = null;
124
+ this.clearCells();
125
+ }
126
+
127
+ if (view._rowDataGenerator.onCellFieldsChange()) {
128
+ view._rowCache.invalidateExposedLeaves();
129
+ }
130
+
131
+ this.phases = {
132
+ discover: performance.now() - start,
133
+ align: 0,
134
+ plan: 0,
135
+ build: 0,
136
+ project: 0
137
+ };
138
+ }
139
+
140
+ /** Build or reuse the cell rows for the just-generated row tree, and report the timings. */
141
+ generateCells() {
142
+ const {view} = this;
143
+ this.buildCells(view._records.list);
144
+
145
+ // Pivot phases only - base row generation is reported by its own op.
146
+ const {phases} = this;
147
+ view.diagnostics.notePivot({
148
+ paths: this.allPaths.length,
149
+ cells: this.cellRows.length,
150
+ phases,
151
+ elapsed: phases.discover + phases.align + phases.plan + phases.build + phases.project
152
+ });
153
+ }
154
+
155
+ /**
156
+ * Rewrite the cells touched by a tick onto their owning group rows, returning the group rows to
157
+ * push to connected stores - cell rows are never published.
158
+ */
159
+ projectUpdatedRows(updatedRows: Set<BaseRow>, changedFields: Set<string>): Set<BaseRow> {
160
+ const groupRows = new Set<BaseRow>(),
161
+ {exposesLeaves} = this.view;
162
+
163
+ updatedRows.forEach(row => {
164
+ if (row instanceof PivotCellRow) {
165
+ this.projectCell(row, changedFields);
166
+ groupRows.add(row.ownerRow);
167
+ } else {
168
+ if (exposesLeaves && row.isLeaf) {
169
+ this.noteLeafCellFields(row as LeafRow, changedFields);
170
+ }
171
+ groupRows.add(row);
172
+ }
173
+ });
174
+
175
+ return groupRows;
176
+ }
177
+
178
+ /**
179
+ * Declare a Field on `store` for every current cell field. Must run before the store loads -
180
+ * under `projectionOnly`, records are built against the declared fields.
181
+ */
182
+ syncStore(store: Store) {
183
+ const {cellFields, syncedCellFields} = this,
184
+ prior = syncedCellFields.get(store);
185
+
186
+ // An unpivoted view mints a fresh empty array per build - compare emptiness too.
187
+ if (prior === cellFields || (isEmpty(prior) && isEmpty(cellFields))) return;
188
+
189
+ // Replace only the fields declared last time. Root-path entries are the measures' own
190
+ // fields - never stale, so they keep their full spec and outlive the pivot.
191
+ const stale = new Set(prior?.filter(it => !it.path.isRoot).map(it => it.name)),
192
+ retained = store.fields.filter(f => !stale.has(f.name)),
193
+ retainedNames = new Set(retained.map(f => f.name)),
194
+ added = cellFields
195
+ .filter(it => !retainedNames.has(it.name))
196
+ .map(
197
+ ({name, measure}) =>
198
+ new Field({
199
+ name,
200
+ type: measure.type,
201
+ displayName: measure.displayName,
202
+ defaultValue: measure.defaultValue
203
+ })
204
+ );
205
+
206
+ store.setFields([...retained, ...added]);
207
+ syncedCellFields.set(store, cellFields);
208
+ }
209
+
210
+ /**
211
+ * Create the data object for a cell row.
212
+ * @internal
213
+ */
214
+ newCellRowData(): PlainObject {
215
+ const {view} = this,
216
+ ret = view._rowDataGenerator.newCellRowData();
217
+ BaseRow.assignDigest(ret as ViewRowData);
218
+ return ret;
219
+ }
220
+
221
+ //------------------------
222
+ // Implementation
223
+ //------------------------
224
+ private get measures(): CubeField[] {
225
+ return this.view.query.pivot?.measures ?? [];
226
+ }
227
+
228
+ /** Drop all paths and cells, as when the View declines its data. */
229
+ reset() {
230
+ this.discovery = null;
231
+ this.clearCells();
232
+ }
233
+
234
+ private clearCells() {
235
+ this.clearVacatedCells(this.cellRows, EMPTY_CELLS);
236
+ this.allPaths = [];
237
+ this.pathKeys = [];
238
+ this.measureNames = [];
239
+ this.paths = [];
240
+ this.cellFields = [];
241
+ this.cellFieldNamesByPath = new Map();
242
+ this.pathIdx = new Map();
243
+ this.pathParentIdx = new Int32Array(0);
244
+ this.cellRows = [];
245
+ }
246
+
247
+ private buildCells(records: StoreRecord[]) {
248
+ const {view, discovery, phases} = this,
249
+ {_rootRows, exposesLeaves} = view,
250
+ prevCells = this.cellRows;
251
+ if (!discovery || isEmpty(_rootRows)) return this.clearCells();
252
+
253
+ let mark = performance.now();
254
+ const lap = () => {
255
+ const now = performance.now(),
256
+ ret = now - mark;
257
+ mark = now;
258
+ return ret;
259
+ };
260
+
261
+ const {groups, parentOfGroup, innermost, groupIdxOf} = this.enumerateGroups();
262
+ if (isEmpty(groups)) return this.clearCells();
263
+
264
+ // Leaves, aligned to the record order discovery used so path indices carry across.
265
+ const leafRows: LeafRow[] = [],
266
+ leafOwnerGroup: number[] = [],
267
+ leafPathIdx: number[] = [];
268
+ for (let i = 0; i < records.length; i++) {
269
+ const leaf = view._leafMap.get(records[i].id);
270
+ if (!leaf) continue;
271
+
272
+ const pathIdx = discovery.pathIdxOfRecord[i];
273
+
274
+ // Stamped on every leaf, owned or not - its cell-field getters read this.
275
+ if (exposesLeaves) leaf.data._pivotPathIdx = pathIdx;
276
+
277
+ const owner = groupIdxOf.get(leaf.parent);
278
+ if (owner == null) continue;
279
+ leafRows.push(leaf);
280
+ leafOwnerGroup.push(owner);
281
+ leafPathIdx.push(pathIdx);
282
+ }
283
+ if (isEmpty(leafRows)) return this.clearCells();
284
+ phases.align = lap();
285
+
286
+ const structure = buildPivotStructure({
287
+ groupCount: groups.length,
288
+ parentOfGroup: Int32Array.from(parentOfGroup),
289
+ innermost: Uint8Array.from(innermost),
290
+ leafOwnerGroup: Int32Array.from(leafOwnerGroup),
291
+ leafPathIdx: Int32Array.from(leafPathIdx),
292
+ pathCount: discovery.paths.length,
293
+ pathParentIdx: discovery.pathParentIdx,
294
+ pathDepth: discovery.pathDepth,
295
+ maxDepth: discovery.maxDepth
296
+ });
297
+
298
+ phases.plan = lap();
299
+
300
+ this.buildCellRows(structure, groups, leafRows);
301
+ this.clearVacatedCells(prevCells, new Set(this.cellRows));
302
+ phases.build = lap();
303
+
304
+ this.cellRows.forEach(cell => this.projectCell(cell));
305
+ phases.project = lap();
306
+ }
307
+
308
+ /**
309
+ * Null the slots of cells in `prev` but not `live`, cut any update route still pointing at one,
310
+ * and mark their aggregates stale for a later reuse. Cells are sparse, so a vacated cell would
311
+ * otherwise leave its last value on a reused owner row.
312
+ */
313
+ private clearVacatedCells(prev: PivotCellRow[], live: Set<PivotCellRow>) {
314
+ prev?.forEach(cell => {
315
+ if (live.has(cell)) return;
316
+
317
+ cell.children?.forEach(child => {
318
+ if (child.pivotParent === cell) child.pivotParent = null;
319
+ });
320
+ cell.staleAggs = true;
321
+
322
+ const {data} = cell.ownerRow;
323
+ if (clearCellSlots(cell, data, EMPTY_NAMES)) BaseRow.assignDigest(data as ViewRowData);
324
+ });
325
+ }
326
+
327
+ /**
328
+ * Rebuild the published path tree and cell fields only when the structure changed - their
329
+ * identity is the structural-change signal consumers key off.
330
+ */
331
+ private syncPaths(specs: PivotPathSpec[]) {
332
+ // Measures can change while the keys do not.
333
+ const keys = specs.map(s => s.key),
334
+ measureNames = this.measures.map(f => f.name);
335
+ if (
336
+ this.pathKeys &&
337
+ arraysEqual(this.pathKeys, keys) &&
338
+ arraysEqual(this.measureNames, measureNames)
339
+ ) {
340
+ return;
341
+ }
342
+
343
+ const {dimensions, measures} = this.view.query.pivot,
344
+ all: PivotPath[] = specs.map(
345
+ s =>
346
+ new PivotPath({
347
+ dimension: s.dimIdx >= 0 ? dimensions[s.dimIdx] : null,
348
+ value: s.value,
349
+ key: s.key,
350
+ depth: s.depth,
351
+ isEmpty: s.isEmpty
352
+ })
353
+ );
354
+
355
+ specs.forEach(s => {
356
+ if (s.parentIdx >= 0) all[s.parentIdx].children.push(all[s.idx]);
357
+ });
358
+
359
+ const cellFields: PivotCellField[] = [],
360
+ cellFieldNamesByPath = new Map<PivotPath, string[]>(),
361
+ pathIdx = new Map<PivotPath, number>();
362
+ all.forEach((path, idx) => {
363
+ const names = measures.map(vf => pivotCellFieldName(path.key, vf.name));
364
+ cellFieldNamesByPath.set(path, names);
365
+ pathIdx.set(path, idx);
366
+ measures.forEach((measure, i) => {
367
+ cellFields.push({name: names[i], path, measure});
368
+ });
369
+ });
370
+
371
+ this.validateCellFieldNames(cellFields);
372
+
373
+ this.pathKeys = keys;
374
+ this.measureNames = measureNames;
375
+ this.allPaths = all;
376
+ this.paths = all[0].children;
377
+ this.cellFields = cellFields;
378
+ this.cellFieldNamesByPath = cellFieldNamesByPath;
379
+ this.pathIdx = pathIdx;
380
+ this.pathParentIdx = Int32Array.from(specs, s => s.parentIdx);
381
+ }
382
+
383
+ /**
384
+ * A cell field colliding with a Cube field would overwrite it on row data. Root-path entries
385
+ * are the measure itself.
386
+ */
387
+ private validateCellFieldNames(cellFields: PivotCellField[]) {
388
+ const cubeNames = new Set(this.view.cube.fields.map(f => f.name));
389
+ cellFields.forEach(({name, path}) => {
390
+ if (!path.isRoot && cubeNames.has(name)) {
391
+ throw new Error(
392
+ `Generated pivot cell field '${name}' collides with a Cube field of the same ` +
393
+ `name. Rename the Cube field, or change PATH_DELIMITER.`
394
+ );
395
+ }
396
+ });
397
+ }
398
+
399
+ /**
400
+ * Instantiate cell rows bottom-up, then wire both aggregation routes. Cells are ordered by
401
+ * (group, path) with both parents at lower indices, so reverse order is bottom-up on both axes.
402
+ */
403
+ private buildCellRows(structure: PivotStructure, groups: BaseRow[], leafRows: LeafRow[]) {
404
+ const {cellCount, cellGroup, cellPath, childStart, childIdx, cellChildKind} = structure,
405
+ {view, allPaths} = this,
406
+ cellRows: PivotCellRow[] = new Array(cellCount);
407
+
408
+ for (let c = cellCount - 1; c >= 0; c--) {
409
+ const ownerRow = groups[cellGroup[c]],
410
+ pathIdx = cellPath[c],
411
+ path = allPaths[pathIdx],
412
+ isLeafKind = cellChildKind[c] === CHILD_KIND_LEAF,
413
+ children: BaseRow[] = [];
414
+
415
+ for (let i = childStart[c]; i < childStart[c + 1]; i++) {
416
+ children.push(isLeafKind ? leafRows[childIdx[i]] : cellRows[childIdx[i]]);
417
+ }
418
+
419
+ const id = `${ownerRow.id}#${path.key}`,
420
+ row = (cellRows[c] = view._rowCache.getOrCreate(
421
+ id,
422
+ children,
423
+ () => new PivotCellRow(view, id, children, ownerRow, path)
424
+ ));
425
+
426
+ // A cache hit matches id and children only - rebind to this generation's instances.
427
+ row.ownerRow = ownerRow;
428
+ row.path = path;
429
+ }
430
+
431
+ for (let c = 0; c < cellCount; c++) {
432
+ const row = cellRows[c],
433
+ parent = structure.cellParent[c],
434
+ pivotParent = structure.cellPivotParent[c];
435
+ row.parent = parent >= 0 ? cellRows[parent] : null;
436
+ row.pivotParent = pivotParent >= 0 ? cellRows[pivotParent] : null;
437
+ }
438
+
439
+ for (let l = 0; l < leafRows.length; l++) {
440
+ const cell = structure.leafPivotParentCell[l];
441
+ leafRows[l].pivotParent = cell >= 0 ? cellRows[cell] : null;
442
+ }
443
+
444
+ this.cellRows = cellRows;
445
+ }
446
+
447
+ /**
448
+ * Name an updated leaf's cell fields into `changedFields`. They are prototype getters, so they
449
+ * move without being written, and `GridTransactionManager` reads the set as complete.
450
+ */
451
+ private noteLeafCellFields(leaf: LeafRow, changedFields: Set<string>) {
452
+ const cell = leaf.pivotParent as PivotCellRow;
453
+ if (cell) this.cellFieldNames(cell).forEach(name => changedFields.add(name));
454
+ }
455
+
456
+ /** Write a cell's values onto its owning group row, moving the owner's digest if any changed. */
457
+ private projectCell(cell: PivotCellRow, changedFields?: Set<string>) {
458
+ const names = this.cellFieldNames(cell),
459
+ {data, ownerRow} = cell,
460
+ ownerData = ownerRow.data,
461
+ {measures} = this;
462
+
463
+ let changed = clearCellSlots(cell, ownerData, names, changedFields);
464
+ for (let i = 0; i < measures.length; i++) {
465
+ const name = names[i],
466
+ val = data[measures[i].name];
467
+ if (ownerData[name] !== val) {
468
+ ownerData[name] = val;
469
+ changedFields?.add(name);
470
+ changed = true;
471
+ }
472
+ }
473
+
474
+ if (changed) BaseRow.assignDigest(ownerData as ViewRowData);
475
+ }
476
+
477
+ /** A miss means a cached cell outlived its path - `buildCellRows` should have rebound it. */
478
+ private cellFieldNames(cell: PivotCellRow): string[] {
479
+ const ret = this.cellFieldNamesByPath.get(cell.path);
480
+ throwIf(!ret, 'No pivot cell fields for this cell path - stale cached cell row.');
481
+ return ret;
482
+ }
483
+
484
+ /** Flatten the group nodes of the final (post-bucketing) network in DFS preorder. */
485
+ private enumerateGroups() {
486
+ const groups: BaseRow[] = [],
487
+ parentOfGroup: number[] = [],
488
+ innermost: number[] = [],
489
+ groupIdxOf = new Map<BaseRow, number>();
490
+
491
+ const visit = (row: BaseRow, parentIdx: number) => {
492
+ if (row.isLeaf) return;
493
+
494
+ const idx = groups.length;
495
+ groups.push(row);
496
+ parentOfGroup.push(parentIdx);
497
+ innermost.push(row.children?.some(it => it.isLeaf) ? 1 : 0);
498
+ groupIdxOf.set(row, idx);
499
+
500
+ row.children?.forEach(child => visit(child, idx));
501
+ };
502
+ this.view._rootRows.forEach(row => visit(row, -1));
503
+
504
+ return {groups, parentOfGroup, innermost, groupIdxOf};
505
+ }
506
+ }
507
+
508
+ function arraysEqual(a: string[], b: string[]): boolean {
509
+ return a.length === b.length && a.every((v, i) => v === b[i]);
510
+ }
511
+
512
+ /**
513
+ * Point `cell` at the cell fields it is about to write onto its owner, nulling any it wrote last
514
+ * generation and no longer covers. Returns true if a value moved.
515
+ */
516
+ function clearCellSlots(
517
+ row: PivotCellRow,
518
+ data: PlainObject,
519
+ names: string[],
520
+ changedFields?: Set<string>
521
+ ): boolean {
522
+ const prior = row.projectedCellNames;
523
+ row.projectedCellNames = names;
524
+ if (!prior || prior === names) return false;
525
+
526
+ let changed = false;
527
+ prior.forEach(name => {
528
+ if (!names.includes(name) && data[name] != null) {
529
+ data[name] = null;
530
+ changedFields?.add(name);
531
+ changed = true;
532
+ }
533
+ });
534
+ return changed;
535
+ }
536
+
537
+ const EMPTY_NAMES: string[] = [],
538
+ EMPTY_CELLS = new Set<PivotCellRow>();
@@ -0,0 +1,125 @@
1
+ /*
2
+ * This file belongs to Hoist, an application development toolkit
3
+ * developed by Extremely Heavy Industries (www.xh.io | info@xh.io)
4
+ *
5
+ * Copyright © 2026 Extremely Heavy Industries Inc.
6
+ */
7
+
8
+ import type {PlainObject} from '@xh/hoist/core';
9
+ import type {PivotStructureSpec} from './PivotStructure';
10
+
11
+ /**
12
+ * Brute-force reference implementation of the pivot structure, used only to assert the behavior of
13
+ * {@link buildPivotStructure}. Deliberately naive - O(groups x paths x leaves) - so that its
14
+ * correctness is self-evident by inspection. Never used in production code paths.
15
+ *
16
+ * Kept out of `data/index.ts`: import via deep path from test drivers and the Toolbox harness.
17
+ */
18
+
19
+ export interface ReferenceGroupTree {
20
+ groupCount: number;
21
+ /** Group-axis parent of each group; -1 for the synthetic root at index 0. */
22
+ parentOfGroup: Int32Array;
23
+ /** 1 where a group's children are leaf rows rather than further groups. */
24
+ innermost: Uint8Array;
25
+ /** Innermost group owning each leaf. */
26
+ leafOwnerGroup: Int32Array;
27
+ /** Human-readable group path, for failure messages. */
28
+ groupKey: string[];
29
+ }
30
+
31
+ /**
32
+ * Group records hierarchically the way {@link View.groupAndInsertRecords} does - string-keyed
33
+ * `groupBy` per dimension, in first-appearance order - always rooted at a synthetic group 0.
34
+ * Guarantees parents are assigned lower indices than their children.
35
+ */
36
+ export function buildReferenceGroupTree(
37
+ records: ArrayLike<{data: PlainObject}>,
38
+ groupDimNames: string[]
39
+ ): ReferenceGroupTree {
40
+ const parentOf: number[] = [-1],
41
+ innermost: number[] = [0],
42
+ groupKey: string[] = ['root'],
43
+ leafOwner: number[] = new Array(records.length).fill(-1);
44
+
45
+ const recurse = (recIdxs: number[], dimIdx: number, groupIdx: number) => {
46
+ if (dimIdx >= groupDimNames.length) {
47
+ innermost[groupIdx] = 1;
48
+ recIdxs.forEach(i => (leafOwner[i] = groupIdx));
49
+ return;
50
+ }
51
+
52
+ const dimName = groupDimNames[dimIdx],
53
+ buckets = new Map<string, number[]>();
54
+
55
+ recIdxs.forEach(i => {
56
+ const k = String(records[i].data[dimName]);
57
+ let bucket = buckets.get(k);
58
+ if (!bucket) buckets.set(k, (bucket = []));
59
+ bucket.push(i);
60
+ });
61
+
62
+ buckets.forEach((idxs, k) => {
63
+ const childIdx = parentOf.length;
64
+ parentOf.push(groupIdx);
65
+ innermost.push(0);
66
+ groupKey.push(`${groupKey[groupIdx]}/${dimName}=[${k}]`);
67
+ recurse(idxs, dimIdx + 1, childIdx);
68
+ });
69
+ };
70
+
71
+ const all: number[] = [];
72
+ for (let i = 0; i < records.length; i++) all.push(i);
73
+ recurse(all, 0, 0);
74
+
75
+ return {
76
+ groupCount: parentOf.length,
77
+ parentOfGroup: Int32Array.from(parentOf),
78
+ innermost: Uint8Array.from(innermost),
79
+ leafOwnerGroup: Int32Array.from(leafOwner),
80
+ groupKey
81
+ };
82
+ }
83
+
84
+ /**
85
+ * The leaf set of every `(group, path)` cell, computed directly from first principles: a leaf
86
+ * belongs to cell `(g, p)` iff its owning group is `g` or a descendant of `g`, and `p` is a prefix
87
+ * of the leaf's own path. Keyed by `groupIdx * pathCount + pathIdx`, root path (0) included.
88
+ *
89
+ * This is the definition the structure must reproduce - it encodes both which cells are populated
90
+ * and what each one must aggregate.
91
+ */
92
+ export function referenceLeafSets(spec: PivotStructureSpec): Map<number, number[]> {
93
+ const {groupCount, pathCount, parentOfGroup, leafOwnerGroup, leafPathIdx, pathParentIdx} = spec,
94
+ leafCount = leafOwnerGroup.length,
95
+ ret = new Map<number, number[]>();
96
+
97
+ for (let g = 0; g < groupCount; g++) {
98
+ for (let leaf = 0; leaf < leafCount; leaf++) {
99
+ if (!isAncestorOrSelf(g, leafOwnerGroup[leaf], parentOfGroup)) continue;
100
+ for (let p = leafPathIdx[leaf]; p >= 0; p = pathParentIdx[p]) {
101
+ const key = g * pathCount + p;
102
+ let arr = ret.get(key);
103
+ if (!arr) ret.set(key, (arr = []));
104
+ arr.push(leaf);
105
+ }
106
+ }
107
+ }
108
+
109
+ ret.forEach(arr => arr.sort((a, b) => a - b));
110
+ return ret;
111
+ }
112
+
113
+ /** All groups from `g` up to the root, inclusive. */
114
+ export function groupAncestry(g: number, parentOfGroup: ArrayLike<number>): number[] {
115
+ const ret: number[] = [];
116
+ for (let cur = g; cur >= 0; cur = parentOfGroup[cur]) ret.push(cur);
117
+ return ret;
118
+ }
119
+
120
+ function isAncestorOrSelf(anc: number, g: number, parentOfGroup: ArrayLike<number>): boolean {
121
+ for (let cur = g; cur >= 0; cur = parentOfGroup[cur]) {
122
+ if (cur === anc) return true;
123
+ }
124
+ return false;
125
+ }