@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,343 @@
1
+ # CubeGrid Package
2
+
3
+ ## Overview
4
+
5
+ The `/cmp/cubegrid/` package renders a Cube View as a grid: group rows down a tree column, the
6
+ app's own columns beside it, and - when the View's query pivots - one column group per pivot path
7
+ appended to the right, with a column per measure inside each group. It is a specialized
8
+ presentation of the standard `Grid`, in the same way `ZoneGrid` and `DataView` are -
9
+ `CubeGridModel` owns a `GridModel` and keeps its store and columns in step with the View.
10
+
11
+ **Key features:**
12
+ - One model for any cube-backed grid - the store, tree mode, label column and summary row are
13
+ wired for you, with or without pivoting
14
+ - Columns derived from the data when pivoting - a new pivot value becomes a new column group,
15
+ appended after the app's columns
16
+ - Nested column groups for two or more pivot dimensions, with a summary column per group
17
+ - Docked row summaries and a docked summary row, each optional and placeable
18
+ - Settings per pivot dimension - sort, collapsing, summaries, labels and classes - and column
19
+ config per measure applied across every path
20
+ - Live updates: ticks reach the cells in place, and column state survives a structural rebuild
21
+ - Ordinary Store fields behind every cell, so column filters, export and selection work as usual
22
+
23
+ All query configuration - row dimensions, pivot dimensions, measures, filters - lives on the
24
+ View's `Query`. `CubeGridModel` holds only presentation config, and apps reconfigure by calling
25
+ `view.updateQuery()`. See the [Cube README](../../data/cube/README.md#pivoting-with-pivot) for the
26
+ data layer, including how cells are named and how they stay current.
27
+
28
+ This guide covers how the pieces fit together. For every configuration key and prop with its
29
+ defaults, see the JSDoc on `CubeGridConfig`, `CubeGridPivotConfig` and `CubeGridProps`.
30
+
31
+ ## Architecture
32
+
33
+ ```
34
+ Cube # Source records
35
+ └── View # Supplied by the app, or created from `cube` + `query`
36
+ └── result.paths, result.cellFields # Structural-change signals, when pivoted
37
+
38
+ CubeGridModel
39
+ ├── view: View # Bound for life - not swappable
40
+ ├── store: Store # Minted from the view; fields track the cell fields
41
+ ├── gridModel: GridModel # The grid rendered; treeMode, managed columns
42
+ ├── selectedRecord, selectAsync, ... # Selection and `empty` delegated, as on ZoneGridModel
43
+ ├── columns # The app's fixed columns, label column first by default
44
+ ├── pivotModel: CubeGridPivotModel # Builds, sizes and expands the pivot region
45
+ │ ├── dimensions, dimensionDefaults # Per dimension: sort, collapsing, summaries, labels, classes
46
+ │ ├── measures, measureDefaults # Per measure: column config applied across every path
47
+ │ ├── availableDimensions, availableMeasures # What a pivot picker offers
48
+ │ ├── measuresOutermost # Measures outermost, paths beneath (default false; 2+ measures)
49
+ │ ├── showRootGroup # Root group over the region (default true)
50
+ │ ├── linkedSizing # One width per measure: true|false|{headerFitMaxWidth}
51
+ │ ├── expandLevel # Pivot header level, as expandLevel for rows
52
+ │ └── expandToLevel(), expandAll(), collapseAll()
53
+ ├── showSummary # The grid's summary row, delegated - needs includeRoot
54
+ └── rebuildColumns() # Runs when result.paths, `columns` or a pivot option changes
55
+
56
+ CubeGrid # Renders gridModel; layout props and agOptions
57
+ ```
58
+
59
+ ## CubeGridModel
60
+
61
+ ### Basic Usage
62
+
63
+ Give the model a Cube and a query, and it creates and owns a connected View. The grid can be built
64
+ before the Cube has data - columns for pivot paths appear as the data arrives.
65
+
66
+ ```typescript
67
+ import {cubeGrid, CubeGridModel} from '@xh/hoist/cmp/cubegrid';
68
+ import {Cube} from '@xh/hoist/data';
69
+
70
+ class PositionsModel extends HoistModel {
71
+ @managed cube = new Cube({
72
+ idSpec: 'id',
73
+ fields: [
74
+ {name: 'fund', type: 'string', isDimension: true},
75
+ {name: 'trader', type: 'string', isDimension: true},
76
+ {name: 'region', type: 'string', isDimension: true},
77
+ {name: 'mktVal', type: 'number', aggregator: 'SUM'},
78
+ {name: 'pnl', type: 'number', aggregator: 'SUM'}
79
+ ]
80
+ });
81
+
82
+ @managed cubeGridModel = new CubeGridModel({
83
+ cube: this.cube,
84
+ query: {
85
+ dimensions: ['fund', 'trader'],
86
+ includeRoot: true,
87
+ pivot: {dimensions: ['region'], measures: ['mktVal', 'pnl']}
88
+ },
89
+ gridConfig: {showSummary: 'top', sizingMode: 'compact', autosizeOptions: {mode: 'managed'}},
90
+ pivotConfig: {
91
+ measures: [
92
+ {field: 'mktVal', column: {width: 120, renderer: millionsRenderer({precision: 2})}},
93
+ {field: 'pnl', column: {width: 110, renderer: numberRenderer({colorSpec: true})}}
94
+ ],
95
+ dimensionDefaults: {showSummary: true}
96
+ }
97
+ });
98
+
99
+ override async doLoadAsync(loadSpec) {
100
+ await this.cube.loadDataAsync(await this.fetchPositionsAsync(loadSpec));
101
+ }
102
+ }
103
+
104
+ // In the component:
105
+ cubeGrid({model: model.cubeGridModel})
106
+ ```
107
+
108
+ Pass `view` instead of `cube` and `query` to bind a View the app already holds, such as one shared
109
+ with a chart. The app then owns the View's lifecycle, and two models may bind to one View.
110
+
111
+ ### A Grid Without Pivoting
112
+
113
+ Leave `pivot` off the query and the model is a plain cube grid: tree-mode, summary row following
114
+ `includeRoot`, and the columns the app lists. This replaces the `GridModel` + `createView({stores})`
115
+ wiring that cube-backed grids used to need.
116
+
117
+ ```typescript
118
+ new CubeGridModel({
119
+ cube,
120
+ query: {dimensions: ['fund', 'trader'], includeRoot: true},
121
+ columns: [
122
+ {field: 'mktVal', renderer: millionsRenderer({precision: 2, label: true})},
123
+ {field: 'pnl', renderer: numberRenderer({precision: 0, colorSpec: true})}
124
+ ]
125
+ });
126
+ ```
127
+
128
+ ### Fixed Columns and Pivot Columns
129
+
130
+ The grid has two regions, always in this order:
131
+
132
+ 1. **Fixed columns** - `columns`, written by the app exactly as for a `GridModel`, in the order
133
+ given. Unless one of them sets `isTreeColumn`, a label column for the row dimensions is placed
134
+ first, pinned left. Bind these to the View's fields: a row attribute carried by a `UNIQUE` or
135
+ `SINGLE` aggregator, a leaf field, or a measure. A measure's bare field name is its row summary,
136
+ so `{field: 'mktVal'}` shows market value once even when the query pivots P&L by region.
137
+ 2. **Pivot columns** - derived from `result.paths` when the query pivots, one group per path with a
138
+ column per `pivot.measures` entry, configured through `pivotConfig.measures`. One group spans the
139
+ region, titled by the first pivot dimension (`By Region`), with every dimension and measure in its
140
+ tooltip (`Mkt Val, Pnl by Region › Sector`). Both name fields by their `shortDisplayName`.
141
+ `showRootGroup: false` drops that group to save a header row, so the top-level path groups head
142
+ the region and it no longer collapses to the row summary - which then shows only if the first
143
+ dimension's `showSummary` asks for it. Multiple measures outermost keep their roots, as those
144
+ name the measures.
145
+
146
+ Column groups in the pivot region expand and collapse from their headers. Each pivot dimension has a
147
+ summary that aggregates its values: the first dimension's is the row summary, which the region
148
+ collapses to, and each later dimension's is the summary its parent groups collapse to - one column
149
+ per measure, under a header labelled `Total` by default. A summary takes each measure's own
150
+ aggregator, so it is an average for an `AVG` measure. Each dimension's `collapsible`,
151
+ `showSummary` and `summaryLabel` govern its own summary: whether groups can collapse to it,
152
+ whether it shows while expanded too, on the side named - the left by default, so the summary keeps
153
+ its collapsed position and the group opens to its right - and its label. The label stays in place
154
+ either way, so collapsing never changes the header depth, unless `showCollapsedLabel: false` drops
155
+ it while collapsed and the summary's column headers stretch up to the group's.
156
+ `pivotConfig.expandLevel` sets the initial level, as `expandLevel` does for rows: 0 collapses the
157
+ region, 1 shows the top-level groups collapsed, -1 (the default) expands everything.
158
+ `pivotModel.expandToLevel()` resets it later, with `expandAll()` and `collapseAll()` as shortcuts.
159
+ The header menu offers the same over pivot columns, via its `expandCollapse` token. Its "Expand
160
+ to..." lists the pivot dimensions, as the row menu lists the row dimensions, which the model
161
+ supplies as `levelLabels` unless the app sets its own.
162
+ The state is the grid's own `columnGroupState`, keyed on the path and on `PIVOT_GROUP_ID` for the
163
+ region, so it survives a rebuild and persists with `persistWith`.
164
+
165
+ ```typescript
166
+ pivotConfig: {
167
+ dimensions: [
168
+ {field: 'region', sortBy: ['US', 'EU'], summaryLabel: 'All Regions'},
169
+ {field: 'sector', collapsible: false} // Regions fixed open to their sectors
170
+ ],
171
+ dimensionDefaults: {showSummary: true} // Every summary shown while expanded
172
+ }
173
+ ```
174
+
175
+ Settings apply in order: built-in defaults, then `dimensionDefaults`, then the dimension's own
176
+ entry. A dimension's entry follows it to whatever level the query pivots it at, and an entry for a
177
+ dimension the query does not pivot on is ignored.
178
+
179
+ A dimension also sets how its values look. `valueRenderer` formats a value's header text, which
180
+ export headers and width fitting use too - a date as `Nov 2026`, say - and `emptyLabel` heads a
181
+ null or blank value, `(empty)` by default. `valueClass` puts a class on a
182
+ value's header and on every header and cell beneath it, and as a function picks one per value, to
183
+ set one apart. `summaryClass` marks the dimension's summary columns. Every summary column and header
184
+ also carries the built-in `xh-cube-grid__summary-cell` and `xh-cube-grid__summary-header` classes,
185
+ unstyled, so a stylesheet can treat all summaries alike or one dimension's apart:
186
+
187
+ ```typescript
188
+ dimensions: [
189
+ {field: 'region', summaryClass: 'row-summary'},
190
+ {
191
+ field: 'month',
192
+ valueRenderer: v => fmtDate(v, 'MMM YYYY'),
193
+ valueClass: v => (v === currentMonth ? 'current-month' : null)
194
+ }
195
+ ]
196
+ ```
197
+
198
+ `dimensions` and `measures` also declare what the grid offers, as `columns` do for a column
199
+ chooser. A picker for the pivot reads `pivotModel.availableDimensions` and `availableMeasures`:
200
+ the listed fields in their listed order, or every one of the cube's `dimensions` and `measures`
201
+ when none are listed. A query may still pivot on a field that is not listed, with the defaults.
202
+
203
+ With `linkedSizing` (the default), every pivot column of a measure shares one width, so the
204
+ region reads as a regular grid. That width is the measure's widest data. Where a displayed pivot
205
+ label needs more room than the data of the columns it spans - a leaf path label over its measures,
206
+ a collapsed group's label over its summary, or with `measuresOutermost` a column's own header - the
207
+ shortfall is shared evenly among those columns, so a narrow measure is not ballooned. Labels claim
208
+ at most `headerFitMaxWidth` (default 140px) and truncate past it, with a tooltip. Data can go
209
+ wider. The width follows as groups expand and collapse. A manual resize moves all of the measure's
210
+ columns together and holds until the next autosize. Set `headerFitMaxWidth: 0` to size for data
211
+ alone, or `linkedSizing: false` to size each column on its own, as in any grid. Set
212
+ `valueRenderer` to shorten labels.
213
+
214
+ Users reorder the fixed columns and the grid persists that through its normal column state. Pivot
215
+ columns are not movable: their order is the view's, set through `sortBy`, in the same way row
216
+ order is set through the query rather than dragged. The regions never interleave. A header drag
217
+ cannot drop a fixed column inside the pivot block, a drop made through the column chooser is moved
218
+ back as soon as it lands, and a rebuild keeps each pivot column's width while taking its position
219
+ from the build.
220
+
221
+ ### Reconfiguring
222
+
223
+ Change what is pivoted through the query, and the grid follows:
224
+
225
+ ```typescript
226
+ const {view} = cubeGridModel;
227
+
228
+ // Pivot on two dimensions instead of one - nested column groups.
229
+ view.updateQuery({pivot: {...view.query.pivot, dimensions: ['region', 'sector']}});
230
+
231
+ // Swap the measures.
232
+ view.updateQuery({pivot: {...view.query.pivot, measures: ['pnl']}});
233
+
234
+ // Switch pivoting off without rebuilding the grid - back to the fixed columns alone.
235
+ view.updateQuery({pivot: null});
236
+ ```
237
+
238
+ `updateQuery` replaces the whole `pivot` block, so spread the current one to change a single member.
239
+ Presentation settings change on the models - `columns` on the CubeGridModel and every pivot option
240
+ on its `pivotModel` are bindable, as are the grid's own on `gridModel`. Dimension and measure
241
+ settings are objects, replaced whole. `showSummary` delegates to the grid.
242
+
243
+ ```typescript
244
+ switchInput({bind: 'measuresOutermost', model: cubeGridModel.pivotModel, label: 'Measures first'})
245
+
246
+ const {pivotModel} = cubeGridModel;
247
+ pivotModel.dimensionDefaults = {...pivotModel.dimensionDefaults, showSummary: 'left'};
248
+ ```
249
+
250
+ ### Pivot Columns and Cell Fields
251
+
252
+ Each cell the View publishes becomes one column, bound to its synthetic field name:
253
+
254
+ | Column | Field on the row | Header |
255
+ |--------|------------------|--------|
256
+ | Row summary for `pnl` | `pnl` | `By Region` › `Total` › `Pnl` |
257
+ | Cell for region `US`, measure `pnl` | `US>>pnl` | `US` › `Pnl` |
258
+ | Summary for `US` with a second pivot dimension | `US>>pnl` | `US` › `Total` › `Pnl` |
259
+ | Cell for `US` › `Tech` | `US>>Tech>>pnl` | `US` › `Tech` › `Pnl` |
260
+
261
+ The field name is also the column's `colId`, so column state persists across rebuilds for paths that
262
+ remain in the data, and a path that leaves and returns comes back at its default width. A summary
263
+ column binds the same cell under a `summary>>` colId, so a fixed column can show the row summary
264
+ for a measure as well. With a dimension's `showCollapsedLabel: false`, a collapsed group's summary
265
+ has no label over it and its own `collapsed>>` colIds. Every path is a group headed by its value
266
+ with a column per measure beneath, even with a single measure, so the measure name stays visible
267
+ beside the fixed columns.
268
+
269
+ `pivotConfig.measures` holds one entry per measure, its `field` naming the measure and its `column`
270
+ the column config applied to every pivot column generated for it, over any in
271
+ `measureDefaults.column` - so the same column specs can serve as the fixed `columns` too. Keys the
272
+ grid sets itself - `colId`, `pinned`, `hidden`, `exportName`, editing and the like - are ignored, so
273
+ a spec shared with the fixed columns still applies cleanly. Pivot columns are not hideable and stay out of the column chooser, as they cannot be moved
274
+ or pinned: the region is the query's. Drop a measure from `pivot.measures` or filter the query to
275
+ remove columns.
276
+
277
+ ### Measures Outermost
278
+
279
+ `measuresOutermost: true` puts each measure outermost, with the paths beneath it, to compare one
280
+ measure across paths. It applies only with multiple measures: a single measure is always laid out
281
+ this way, since nesting it would repeat its name under every path. Its groups keep the default
282
+ layout's ids unless the option is set, so their expand state carries over as measures are added.
283
+
284
+ ```
285
+ Default measuresOutermost: true
286
+ By Region Pnl by Region
287
+ ├── US ├── US: Tech | Energy | Total
288
+ │ ├── Tech: Pnl | MktVal ├── EU: ...
289
+ │ └── ... └── Total
290
+ └── Total: Pnl | MktVal MktVal ...
291
+ ```
292
+
293
+ Each measure is a root group, headed by its column's `headerName` and the first pivot dimension
294
+ (`Pnl by Region`), that collapses to its own row summary - there is no group over the whole region,
295
+ so `PIVOT_GROUP_ID` is not present and the header is one level shallower. Every pivot dimension
296
+ shows in the measure's tooltip. Group ids carry the
297
+ measure, as `pnl::pivot` and `pnl::US`, so each measure expands on its own. Summaries still belong
298
+ to their dimensions, so the first dimension's settings govern each measure's row summary. Leaf paths
299
+ head their columns directly, and each summary is a single column under its own `measureSummary>>`
300
+ colId, so `showCollapsedLabel` has no effect. Cell colIds are the same either way, so their state
301
+ carries over when the option changes.
302
+
303
+ ### Sorting the Pivot Axis
304
+
305
+ Each dimension's `sortBy` orders its values: `'asc'`, `'desc'`, an explicit array of dimension
306
+ values with anything unlisted following in view order, a comparator of two `PivotPath`s, or `null`
307
+ to keep the View's own ascending order. It is display-only; the View's `result.paths` is never
308
+ reordered.
309
+
310
+ ```typescript
311
+ pivotConfig: {
312
+ dimensions: [
313
+ {field: 'region', sortBy: ['US', 'EU']}, // Fixed order
314
+ {field: 'tenor', sortBy: (a, b) => tenorDays(a.value) - tenorDays(b.value)} // 1W, 3M, 1Y
315
+ ]
316
+ }
317
+ ```
318
+
319
+ A comparator runs on each rebuild, not on data changes, so set new `dimensions` to re-sort when what
320
+ it reads changes.
321
+
322
+ ## Filtering and Export
323
+
324
+ A `gridConfig.filterModel` binds to the View by default - `{bind: 'view'}` - so a column filter
325
+ on a dimension or measure filters the **source records** through the query and re-aggregates
326
+ every row, summary and pivot cell, as a pivot table's label filter does. Pivot columns are never
327
+ filterable: a cell is an aggregate, and no query filter can express a condition on it.
328
+
329
+ Bind to the store instead - `filterModel: {bind: 'store'}` - to filter the **group
330
+ rows by their aggregates** with no re-aggregation, as a pivot table's value filter does. A row
331
+ then passes on its own aggregates, and a failing parent stays visible while a child passes. The two
332
+ are different operations and both are useful.
333
+
334
+ Export is leaf-columns-only, and a pivot column's header repeats under every path, so each pivot
335
+ column exports under its path labels and header joined - `US › Tech › P&L`, `Total › P&L`. The
336
+ header is the column's `headerName`, or the field's display name when the header is an element.
337
+ `exportName` is reserved on pivot columns, since one shared with the fixed columns would repeat.
338
+
339
+ ## Related Packages
340
+
341
+ - [`/data/cube/`](../../data/cube/README.md) - Cube, Query and View, including the `pivot` option
342
+ - [`/cmp/grid/`](../grid/README.md) - GridModel and Column, which this package builds on
343
+ - `/cmp/zoneGrid/` - another specialized presentation of a GridModel
@@ -0,0 +1,105 @@
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
+ import type {ColumnSpec} from '@xh/hoist/cmp/grid';
8
+ import type {HSide} from '@xh/hoist/core';
9
+ import type {PivotPath} from '@xh/hoist/data';
10
+
11
+ /**
12
+ * Display sort for the values of one pivot dimension.
13
+ *
14
+ * `'asc'` / `'desc'` sort by raw dimension value. An array is an explicit ordering of raw dimension
15
+ * values, with anything unlisted following in the view's own ascending order. A comparator orders
16
+ * the paths, as `Array.sort` does - it runs on each rebuild, so set new `dimensions` to re-sort
17
+ * when what it reads changes. `null` leaves the dimension in that view order.
18
+ */
19
+ export type PivotSort = 'asc' | 'desc' | any[] | ((a: PivotPath, b: PivotPath) => number);
20
+
21
+ /**
22
+ * Display settings for one pivot dimension - see {@link CubeGridPivotConfig.dimensions}.
23
+ *
24
+ * A dimension's summary aggregates its values: the first dimension's is the row summary, which
25
+ * the region collapses to, and each later dimension's is the summary its parent groups collapse to.
26
+ */
27
+ export interface PivotDimensionSpec {
28
+ /** Name of the pivot dimension. */
29
+ field: string;
30
+
31
+ /** Display order of the dimension's values. Default null, keeping view order. */
32
+ sortBy?: PivotSort;
33
+
34
+ /**
35
+ * True (default) to let groups collapse to this dimension's summary. False to fix them open,
36
+ * with the summary shown only where `showSummary` asks for it.
37
+ */
38
+ collapsible?: boolean;
39
+
40
+ /**
41
+ * Show this dimension's summary while its groups are expanded too, as
42
+ * {@link GridConfig.showSummary} is the summary row. True for the default 'left', where the
43
+ * summary keeps its collapsed position and the group opens to its right, or an {@link HSide}
44
+ * to place it within the group. Default false - a collapsed group always shows it.
45
+ */
46
+ showSummary?: boolean | HSide;
47
+
48
+ /** Header of this dimension's summary, and its name in export headers. Default 'Total'. */
49
+ summaryLabel?: string;
50
+
51
+ /**
52
+ * True (default) to show `summaryLabel` over the summary while its group is collapsed. False
53
+ * to drop it, so the summary's column headers stretch up to the group's. No effect with
54
+ * measures outermost, or a single measure, where a summary is one column headed by its label.
55
+ */
56
+ showCollapsedLabel?: boolean;
57
+
58
+ /**
59
+ * Class for this dimension's summary columns, cells and headers, over the built-in
60
+ * `xh-cube-grid__summary-cell` and `xh-cube-grid__summary-header` classes every summary
61
+ * carries - to style the row summary apart from the others, say.
62
+ */
63
+ summaryClass?: string;
64
+
65
+ /**
66
+ * Header text for one of the dimension's values - a date as 'Nov 2026', say. Also used in
67
+ * export headers and to fit widths. Not called for an empty value, which takes `emptyLabel`.
68
+ * Default the value as a string.
69
+ */
70
+ valueRenderer?: (value: any, path: PivotPath) => string;
71
+
72
+ /**
73
+ * Class for each of the dimension's values, on its header and on every header and cell
74
+ * beneath it - nested values and their summaries included. A function picks it per value,
75
+ * with `value` null for an empty one, to set one apart, such as the current month.
76
+ */
77
+ valueClass?: string | ((value: any, path: PivotPath) => string);
78
+
79
+ /** Header text for a null / blank value of the dimension. Default '(empty)'. */
80
+ emptyLabel?: string;
81
+ }
82
+
83
+ /** Settings for one pivot measure - see {@link CubeGridPivotConfig.measures}. */
84
+ export interface PivotMeasureSpec {
85
+ /** Name of the measure, a `pivot.measures` entry. */
86
+ field: string;
87
+
88
+ /**
89
+ * Column config applied to every pivot column built for the measure, under every path -
90
+ * renderer, width, align, and so on. Its `headerName` heads the measure's columns. Keys the
91
+ * grid sets itself - identity, placement, visibility, export name, editing and `agOptions` -
92
+ * are ignored, so a spec shared with the fixed `columns` applies cleanly.
93
+ */
94
+ column?: Partial<ColumnSpec>;
95
+ }
96
+
97
+ /** Options for {@link CubeGridPivotConfig.linkedSizing}. */
98
+ export interface PivotLinkedSizingOptions {
99
+ /**
100
+ * Most a pivot label can claim to fit, in pixels across the columns it spans - a group's, or
101
+ * with `measuresOutermost` a column's own header. Default 140. Data can widen the columns past
102
+ * it. 0 to size for data alone.
103
+ */
104
+ headerFitMaxWidth?: number;
105
+ }
@@ -0,0 +1,10 @@
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
+ export * from './CubeGrid';
8
+ export * from './CubeGridModel';
9
+ export * from './CubeGridPivotModel';
10
+ export type * from './Types';
@@ -9,6 +9,10 @@ import type {
9
9
  ColumnRenderer,
10
10
  ColumnSpec,
11
11
  GridConfig,
12
+ GridEnsureVisibleOptions,
13
+ GridLikeModel,
14
+ GridSelectFirstOptions,
15
+ GridSelectOptions,
12
16
  GroupRowRenderer,
13
17
  RowClassFn,
14
18
  RowClassRuleFn,
@@ -152,7 +156,7 @@ export type ItemHeightFn = (params: {
152
156
  * @see DataView
153
157
  * @see DataViewConfig
154
158
  */
155
- export class DataViewModel extends HoistModel {
159
+ export class DataViewModel extends HoistModel implements GridLikeModel {
156
160
  @managed gridModel: GridModel;
157
161
  @bindableRef accessor itemHeight: number | ItemHeightFn;
158
162
  @bindable accessor groupRowHeight: number;
@@ -236,6 +240,10 @@ export class DataViewModel extends HoistModel {
236
240
  get store() {
237
241
  return this.gridModel.store;
238
242
  }
243
+ get innerGridModel(): GridModel {
244
+ return this.gridModel;
245
+ }
246
+
239
247
  get empty() {
240
248
  return this.gridModel.empty;
241
249
  }
@@ -261,10 +269,7 @@ export class DataViewModel extends HoistModel {
261
269
  return this.gridModel.sortBy;
262
270
  }
263
271
 
264
- selectAsync(
265
- records: Some<StoreRecordOrId>,
266
- opts?: {ensureVisible?: boolean; clearSelection?: boolean}
267
- ) {
272
+ selectAsync(records: Some<StoreRecordOrId>, opts?: GridSelectOptions) {
268
273
  return this.gridModel.selectAsync(records, opts);
269
274
  }
270
275
 
@@ -272,12 +277,12 @@ export class DataViewModel extends HoistModel {
272
277
  return this.gridModel.preSelectFirstAsync();
273
278
  }
274
279
 
275
- selectFirstAsync(opts: {ensureVisible?: boolean} = {}) {
280
+ selectFirstAsync(opts?: GridSelectFirstOptions) {
276
281
  return this.gridModel.selectFirstAsync(opts);
277
282
  }
278
283
 
279
- ensureSelectionVisibleAsync() {
280
- return this.gridModel.ensureSelectionVisibleAsync();
284
+ ensureSelectionVisibleAsync(opts?: GridEnsureVisibleOptions) {
285
+ return this.gridModel.ensureSelectionVisibleAsync(opts);
281
286
  }
282
287
 
283
288
  override doLoadAsync(loadSpec: LoadSpec) {
@@ -16,6 +16,7 @@
16
16
  display: flex;
17
17
  flex-direction: row;
18
18
  align-items: center;
19
+ gap: var(--xh-pad-half-px);
19
20
  min-height: 32px;
20
21
  width: 100%;
21
22
 
@@ -23,8 +24,9 @@
23
24
  cursor: pointer;
24
25
  }
25
26
 
27
+ // The label sizes to its text, so the expand control sits right after it.
26
28
  span {
27
- flex: 1;
29
+ min-width: 0;
28
30
  overflow: hidden;
29
31
  text-overflow: ellipsis;
30
32
  }
@@ -71,17 +73,21 @@
71
73
  }
72
74
 
73
75
  .xh-column-header-align-right {
74
- .xh-grid-header,
75
- .xh-grid-group-header {
76
+ .xh-grid-header {
76
77
  text-align: right;
77
78
  }
79
+ .xh-grid-group-header {
80
+ justify-content: flex-end;
81
+ }
78
82
  }
79
83
 
80
84
  .xh-column-header-align-center {
81
- .xh-grid-header,
82
- .xh-grid-group-header {
85
+ .xh-grid-header {
83
86
  text-align: center;
84
87
  }
88
+ .xh-grid-group-header {
89
+ justify-content: center;
90
+ }
85
91
  }
86
92
 
87
93
  // Pinned-row containers host total rows.
@@ -477,6 +483,16 @@
477
483
  display: block;
478
484
  }
479
485
 
486
+ // Spaced as the expand icon of a group header.
487
+ .xh-grid-header-expand-icon {
488
+ display: none;
489
+ margin-left: var(--xh-pad-half-px);
490
+ }
491
+
492
+ &--expand .xh-grid-header-expand-icon {
493
+ display: block;
494
+ }
495
+
480
496
  &--large {
481
497
  font-size: var(--xh-grid-large-header-font-size-px);
482
498
  padding: 0 var(--xh-grid-large-header-lr-pad-px);