@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
@@ -1,5 +1,4 @@
1
- import type { GridModel } from '@xh/hoist/cmp/grid';
2
- import type { ZoneGridModel } from '@xh/hoist/cmp/zoneGrid';
1
+ import type { GridLikeModel } from '@xh/hoist/cmp/grid';
3
2
  import type { DefaultHoistProps, HoistModel } from '@xh/hoist/core';
4
3
  import type { FilterMatchMode, FilterTestFn, Store } from '@xh/hoist/data';
5
4
  export interface StoreFilterFieldProps extends DefaultHoistProps {
@@ -24,12 +23,12 @@ export interface StoreFilterFieldProps extends DefaultHoistProps {
24
23
  */
25
24
  filterBuffer?: number;
26
25
  /**
27
- * GridModel or ZoneGridModel whose Store this control should filter. When given a GridModel,
28
- * this component will, by default, use the fields for all *visible* columns when matching, as
29
- * well as any groupBy field. When given a ZoneGridModel, it uses the fields currently mapped
30
- * to any of its zones. Do not configure this and `store` on the same component.
26
+ * Model whose Store this control should filter. When given a GridModel or CubeGridModel, this
27
+ * component will, by default, use the fields for all *visible* columns when matching, as well
28
+ * as any groupBy field. When given a ZoneGridModel, it uses the fields currently mapped to any
29
+ * of its zones. Do not configure this and `store` on the same component.
31
30
  */
32
- gridModel?: GridModel | ZoneGridModel;
31
+ gridModel?: GridLikeModel;
33
32
  /**
34
33
  * Names of field(s) to include in search. Required if neither a store nor gridModel are
35
34
  * provided, as otherwise fields cannot be inferred.
@@ -64,8 +63,8 @@ export interface StoreFilterFieldProps extends DefaultHoistProps {
64
63
  * object itself is considered a match.
65
64
  *
66
65
  * This component is designed to be bound to a Store via either its `store` OR `gridModel` props,
67
- * the latter accepting either a GridModel or a ZoneGridModel. If not configured with either, it
68
- * binds by default to the nearest GridModel or ZoneGridModel found in context. Binding in this way
66
+ * the latter accepting a GridModel, ZoneGridModel or CubeGridModel. If not configured with either,
67
+ * it binds by default to the nearest such model found in context. Binding in this way
69
68
  * allows the component to auto-generate the fields in the store to be included in the filter and
70
69
  * to automatically apply the filter to the Store.
71
70
  *
@@ -1,5 +1,4 @@
1
- import { GridModel } from '@xh/hoist/cmp/grid';
2
- import { ZoneGridModel } from '@xh/hoist/cmp/zoneGrid';
1
+ import type { GridLikeModel } from '@xh/hoist/cmp/grid';
3
2
  import { HoistModel } from '@xh/hoist/core';
4
3
  import type { FilterMatchMode, StoreRecord, Store } from '@xh/hoist/data';
5
4
  /**
@@ -11,8 +10,8 @@ export declare class StoreFilterFieldImplModel extends HoistModel {
11
10
  private filter;
12
11
  private bufferedApplyFilter;
13
12
  get matchMode(): FilterMatchMode;
14
- /** GridModel or ZoneGridModel to filter - from props, or the nearest found in context. */
15
- get boundModel(): GridModel | ZoneGridModel;
13
+ /** Model to filter - from props, or the nearest found in context. */
14
+ get boundModel(): GridLikeModel;
16
15
  get store(): Store;
17
16
  onLinked(): void;
18
17
  get filterText(): string;
@@ -25,6 +24,7 @@ export declare class StoreFilterFieldImplModel extends HoistModel {
25
24
  /**
26
25
  * Columns whose fields the user can see, and so should be able to search. A ZoneGrid renders
27
26
  * its mapped fields within two zone columns, so use the columns backing those fields instead.
27
+ * A DataView renders every field through one item renderer, so search them all.
28
28
  */
29
29
  private getSearchColumns;
30
30
  }
@@ -1,5 +1,5 @@
1
1
  import type { CellClickedEvent, CellContextMenuEvent, CellDoubleClickedEvent, RowClickedEvent, RowDoubleClickedEvent } from '@xh/hoist/kit/ag-grid';
2
- import type { ColumnRenderer, ColumnSpec, GridContextMenuItemLike, GridContextMenuSpec, GridGroupSortFn, GridSorterLike, GroupRowRenderer, RowClassFn, RowClassRuleFn, TreeStyle } from '@xh/hoist/cmp/grid';
2
+ import type { ColumnRenderer, ColumnSpec, GridContextMenuItemLike, GridContextMenuSpec, GridEnsureVisibleOptions, GridGroupSortFn, GridLikeModel, GridSelectFirstOptions, GridSelectOptions, GridSorterLike, GroupRowRenderer, RowClassFn, RowClassRuleFn, TreeStyle } from '@xh/hoist/cmp/grid';
3
3
  import { Column, GridModel, GridSorter } from '@xh/hoist/cmp/grid';
4
4
  import type { Awaitable, LoadSpec, PlainObject, Some, Thunkable, VSide } from '@xh/hoist/core';
5
5
  import { HoistModel } from '@xh/hoist/core';
@@ -220,7 +220,7 @@ export interface ZoneGridConfig {
220
220
  * @see ZoneGrid
221
221
  * @see ZoneGridConfig
222
222
  */
223
- export declare class ZoneGridModel extends HoistModel {
223
+ export declare class ZoneGridModel extends HoistModel implements GridLikeModel {
224
224
  gridModel: GridModel;
225
225
  mapperModel: ZoneMapperModel;
226
226
  accessor mappings: Record<Zone, ZoneMapping[]>;
@@ -253,6 +253,7 @@ export declare class ZoneGridModel extends HoistModel {
253
253
  get sortBy(): GridSorter;
254
254
  setSortBy(cfg: GridSorterLike): void;
255
255
  get store(): Store;
256
+ get innerGridModel(): GridModel;
256
257
  get empty(): boolean;
257
258
  get selModel(): StoreSelectionModel;
258
259
  get hasSelection(): boolean;
@@ -260,15 +261,10 @@ export declare class ZoneGridModel extends HoistModel {
260
261
  get selectedRecord(): import("@xh/hoist/data").StoreRecord;
261
262
  get selectedId(): import("@xh/hoist/data").StoreRecordId;
262
263
  get groupBy(): string[];
263
- selectAsync(records: Some<StoreRecordOrId>, opts: {
264
- ensureVisible?: boolean;
265
- clearSelection?: boolean;
266
- }): Promise<void>;
264
+ selectAsync(records: Some<StoreRecordOrId>, opts?: GridSelectOptions): Promise<void>;
267
265
  preSelectFirstAsync(): Promise<void>;
268
- selectFirstAsync(opts?: {
269
- ensureVisible?: boolean;
270
- }): Promise<void>;
271
- ensureSelectionVisibleAsync(): Promise<void>;
266
+ selectFirstAsync(opts?: GridSelectFirstOptions): Promise<void>;
267
+ ensureSelectionVisibleAsync(opts?: GridEnsureVisibleOptions): Promise<void>;
272
268
  doLoadAsync(loadSpec: LoadSpec): Promise<any>;
273
269
  loadData(rawData: any[], rawSummaryData?: Some<PlainObject>): void;
274
270
  updateData(rawData: PlainObject[] | StoreTransaction): import("@xh/hoist/data").StoreChangeLog;
@@ -6,6 +6,12 @@ import type { DebounceSettings } from 'lodash';
6
6
  import type { Route } from 'router5';
7
7
  /** Values available for intents. */
8
8
  export type Intent = 'primary' | 'success' | 'warning' | 'danger';
9
+ /**
10
+ * Sizes a component can be drawn at, chosen by the developer for emphasis or space. Distinct from
11
+ * `SizingMode`, the density preference that a user can change for the whole app. A component
12
+ * that takes this type may support only some of the sizes.
13
+ */
14
+ export type ComponentSize = 'compact' | 'standard' | 'large';
9
15
  /** Values available for App Theme. */
10
16
  export type Theme = 'system' | 'dark' | 'light';
11
17
  export type Side = 'top' | 'bottom' | 'left' | 'right';
@@ -13,6 +13,12 @@ export interface FieldSpec {
13
13
  * transformed via `genDisplayName()` (e.g. 'myField' translates to 'My Field').
14
14
  */
15
15
  displayName?: string;
16
+ /**
17
+ * Shorter name for headers, where space is tight - a grid column's default `headerName`, and a
18
+ * pivot grid's headers. Choosers, menus and exports keep `displayName`. Defaults to
19
+ * `displayName`.
20
+ */
21
+ shortDisplayName?: string;
16
22
  /** Supplementary descriptive text for this field, for use in tooltips and other UI. */
17
23
  description?: string;
18
24
  /**
@@ -54,12 +60,13 @@ export declare class Field {
54
60
  readonly name: string;
55
61
  readonly type: FieldType;
56
62
  readonly displayName: string;
63
+ readonly shortDisplayName: string;
57
64
  readonly description: string;
58
65
  readonly defaultValue: any;
59
66
  readonly isDimension: boolean;
60
67
  readonly rules: Rule[];
61
68
  readonly enableXssProtection: boolean;
62
- constructor({ name, type, displayName, description, defaultValue, isDimension, rules, enableXssProtection }: FieldSpec);
69
+ constructor({ name, type, displayName, shortDisplayName, description, defaultValue, isDimension, rules, enableXssProtection }: FieldSpec);
63
70
  parseVal(val: any): any;
64
71
  isEqual(val1: any, val2: any): boolean;
65
72
  private processRuleSpecs;
@@ -203,6 +203,10 @@ export interface StoreTransaction {
203
203
  * supply them cheaply. Providing this asserts that updates change record values only - no
204
204
  * structural/parent changes - and that no field outside the set changed. Enables downstream
205
205
  * consumers (e.g. Grid) to prove a change cannot affect sort order and skip re-sorting.
206
+ *
207
+ * Cube Views rely on it too: a set naming no dimension or bucket field lets a View skip its
208
+ * per-record structural check, so a set that omits a changed dimension leaves the View's row
209
+ * hierarchy stale.
206
210
  */
207
211
  changedFields?: Set<string>;
208
212
  }
@@ -292,6 +296,7 @@ export declare class Store extends HoistBase implements FilterBindTarget, Filter
292
296
  private accessor _committed;
293
297
  private accessor _current;
294
298
  accessor _filtered: RecordSet;
299
+ private _fieldDefaults;
295
300
  private _dataTemplate;
296
301
  private _dataDefaults;
297
302
  private _denseRecordThreshold;
@@ -448,6 +453,13 @@ export declare class Store extends HoistBase implements FilterBindTarget, Filter
448
453
  * removing any uncommitted records added locally, and restoring any uncommitted deletes.
449
454
  */
450
455
  revert(): void;
456
+ /**
457
+ * Replace this Store's fields wholesale, re-applying `fieldDefaults` and rebuilding the derived
458
+ * field map and data defaults. Drops all records, which were built against the outgoing
459
+ * defaults - callers reload immediately.
460
+ * @internal - supports pivoted Views, whose cell fields are discovered from data.
461
+ */
462
+ setFields(fields: Array<string | FieldSpec | Field>): void;
451
463
  /** Get a specific Field by name.*/
452
464
  getField(name: string): Field;
453
465
  get fieldNames(): string[];
@@ -136,6 +136,8 @@ export declare class Cube extends HoistBase {
136
136
  get fields(): CubeField[];
137
137
  /** Dimension Fields configured for this Cube. */
138
138
  get dimensions(): CubeField[];
139
+ /** Fields a pivot can show as measures - those with an aggregator, other than dimensions. */
140
+ get measures(): CubeField[];
139
141
  /** Records loaded in to this Cube. */
140
142
  get records(): StoreRecord[];
141
143
  /** True if this Cube contains no data / records. */
@@ -1,6 +1,6 @@
1
1
  import type { PlainObject } from '@xh/hoist/core';
2
2
  import type { AggregationContext, FieldSpec } from '@xh/hoist/data';
3
- import { Aggregator, AverageAggregator, AverageStrictAggregator, ChildCountAggregator, Field, LeafCountAggregator, MaxAggregator, MinAggregator, NullAggregator, SingleAggregator, SumAggregator, SumStrictAggregator, UniqueAggregator } from '@xh/hoist/data';
3
+ import { Aggregator, AverageAggregator, AverageStrictAggregator, ChildCountAggregator, Field, LeafCountAggregator, MaxAggregator, MedianAggregator, MinAggregator, NullAggregator, SingleAggregator, SumAggregator, SumStrictAggregator, UniqueAggregator } from '@xh/hoist/data';
4
4
  export interface CubeFieldSpec extends FieldSpec {
5
5
  /**
6
6
  * Instance of a Hoist Cube {@link Aggregator} or string token alias for one.
@@ -33,7 +33,7 @@ export interface CubeFieldSpec extends FieldSpec {
33
33
  parentDimension?: string;
34
34
  }
35
35
  /** Convenient (and serializable) alias for one of Hoist's Cube {@link Aggregator} classes. */
36
- export type AggregatorToken = 'AVG' | 'AVG_STRICT' | 'CHILD_COUNT' | 'LEAF_COUNT' | 'MAX' | 'MIN' | 'NULL' | 'SINGLE' | 'SUM' | 'SUM_STRICT' | 'UNIQUE';
36
+ export type AggregatorToken = 'AVG' | 'AVG_STRICT' | 'CHILD_COUNT' | 'LEAF_COUNT' | 'MAX' | 'MEDIAN' | 'MIN' | 'NULL' | 'SINGLE' | 'SUM' | 'SUM_STRICT' | 'UNIQUE';
37
37
  /**
38
38
  * @param dimension - dimension of aggregation
39
39
  * @param value - value of record on dimension
@@ -58,6 +58,7 @@ export declare class CubeField extends Field {
58
58
  static childCountAggregator: ChildCountAggregator;
59
59
  static leafCountAggregator: LeafCountAggregator;
60
60
  static maxAggregator: MaxAggregator;
61
+ static medianAggregator: MedianAggregator;
61
62
  static minAggregator: MinAggregator;
62
63
  static nullAggregator: NullAggregator;
63
64
  static singleAggregator: SingleAggregator;
@@ -7,7 +7,8 @@ import { CubeField } from './CubeField';
7
7
  *
8
8
  * Key options beyond `dimensions` and `filter`: `includeRoot` adds a grand-total row,
9
9
  * `includeLeaves` exposes source records as tree children, and `provideLeaves` makes them
10
- * accessible programmatically without rendering in the tree.
10
+ * accessible programmatically without rendering in the tree. `pivot` additionally slices the
11
+ * aggregates across a second axis of dimensions - see {@link PivotSpec}.
11
12
  *
12
13
  * See the Cube package README (`data/cube/README.md#querying-with-views`) for query patterns.
13
14
  *
@@ -22,7 +23,8 @@ export interface QueryConfig {
22
23
  cube?: Cube;
23
24
  /**
24
25
  * Fields or field names. If unspecified will include all available {@link Cube.fields}.
25
- * Specify a subset to optimize aggregation performance.
26
+ * Specify a subset to optimize aggregation performance. `dimensions` and any `pivot` fields
27
+ * are always included.
26
28
  */
27
29
  fields?: string[] | CubeField[];
28
30
  /**
@@ -99,6 +101,50 @@ export interface QueryConfig {
99
101
  * Return true to omit the row. Defaults to Cube.omitFn.
100
102
  */
101
103
  omitFn?: OmitFn;
104
+ /**
105
+ * Pivot additional dimensions into *columns* rather than rows, aggregating measures at each
106
+ * intersection. Omit for an ordinary view - see {@link PivotSpec}.
107
+ */
108
+ pivot?: PivotSpec;
109
+ }
110
+ /**
111
+ * Pivot axis of a {@link QueryConfig} - extra dimensions sliced into columns rather than rows, and
112
+ * the measures aggregated at each intersection. `QueryConfig.dimensions` keeps its meaning as the
113
+ * row hierarchy; the two axes are orthogonal. Results carry the structure as
114
+ * {@link ViewResult.paths} and {@link ViewResult.cellFields}, with each cell value published as a
115
+ * synthetic field on its group row - see `CubeGridModel` for rendering.
116
+ */
117
+ export interface PivotSpec {
118
+ /**
119
+ * Pivot dimensions, outermost first. 1 is typical, 3 the practical ceiling. Empty to degenerate
120
+ * to plain View behavior, so apps can toggle pivoting without swapping view objects.
121
+ */
122
+ dimensions: string[] | CubeField[];
123
+ /**
124
+ * Measures to aggregate per cell - fields with an aggregator, and not `isDimension`. Added to
125
+ * the query's `fields` along with any {@link Aggregator.dependsOn}. Empty degenerates to plain
126
+ * View behavior, as for `dimensions`.
127
+ */
128
+ measures: string[] | CubeField[];
129
+ /**
130
+ * True to exclude records with a null / blank pivot dimension value entirely, via an implicit
131
+ * filter, so they leave the group aggregates too and a row's summary covers the same records
132
+ * as its cells. Default false, which gives such records their own empty path.
133
+ */
134
+ excludeEmptyPivotValues?: boolean;
135
+ /**
136
+ * Decline the result if the discovered pivot path count exceeds this - see
137
+ * {@link ViewResult.exception}. Default 100; null to disable.
138
+ */
139
+ maxPivotPaths?: number;
140
+ }
141
+ /** Resolved form of a {@link PivotSpec}, as held by a {@link Query}. */
142
+ export interface Pivot {
143
+ dimensions: CubeField[];
144
+ dimensionNames: string[];
145
+ measures: CubeField[];
146
+ excludeEmptyPivotValues: boolean;
147
+ maxPivotPaths: number;
102
148
  }
103
149
  /**
104
150
  * {@inheritDoc QueryConfig}
@@ -107,7 +153,8 @@ export interface QueryConfig {
107
153
  */
108
154
  export declare class Query {
109
155
  /**
110
- * Queried fields, sorted by name. Includes `dimensions`, added here if not already present.
156
+ * Queried fields, sorted by name. Includes `dimensions` and pivot fields, added here if not
157
+ * already present.
111
158
  */
112
159
  readonly fields: CubeField[];
113
160
  readonly dimensions: CubeField[];
@@ -121,9 +168,12 @@ export declare class Query {
121
168
  readonly lockFn: LockFn;
122
169
  readonly bucketSpecFn: BucketSpecFn;
123
170
  readonly omitFn: OmitFn;
171
+ /** Resolved pivot spec, or null for an ordinary query. */
172
+ readonly pivot: Pivot;
124
173
  private readonly _rawFields;
174
+ private readonly _rawFilter;
125
175
  private readonly _testFn;
126
- constructor({ cube, fields, dimensions, filter, includeRoot, includeLeaves, provideLeaves, omitRedundantNodes, lockFn, bucketSpecFn, omitFn }: QueryConfig);
176
+ constructor({ cube, fields, dimensions, filter, includeRoot, includeLeaves, provideLeaves, omitRedundantNodes, lockFn, bucketSpecFn, omitFn, pivot }: QueryConfig);
127
177
  clone(overrides: Partial<QueryConfig>): Query;
128
178
  test(record: StoreRecord): boolean;
129
179
  /**
@@ -136,4 +186,16 @@ export declare class Query {
136
186
  equalsExcludingFilter(other: Query): boolean;
137
187
  private parseFields;
138
188
  private parseDimensions;
189
+ /** True if this query pivots on at least one dimension and measure. */
190
+ get isPivoted(): boolean;
191
+ private parsePivot;
192
+ private parseMeasures;
193
+ /** The pivot's own fields plus anything their aggregators read - always queried. */
194
+ private pivotFields;
195
+ /**
196
+ * Fold `excludeEmptyPivotValues` into the query filter as FieldFilters - a `FunctionFilter`
197
+ * compares its `testFn` by reference, which would defeat `View.updateQuery`'s equality check.
198
+ */
199
+ private applyPivotFilter;
200
+ private validatePivot;
139
201
  }
@@ -1,12 +1,18 @@
1
1
  import type { GridFilterBindTarget } from '@xh/hoist/cmp/grid';
2
2
  import type { PlainObject, Some } from '@xh/hoist/core';
3
3
  import { HoistBase } from '@xh/hoist/core';
4
- import type { CubeField, Filter, FilterBindTarget, FilterLike, FilterValueSource, Query, QueryConfig, Store, StoreRecordId } from '@xh/hoist/data';
5
- import { Cube } from '@xh/hoist/data';
4
+ import type { HoistException } from '@xh/hoist/exception';
5
+ import type { CubeField, Filter, FilterBindTarget, FilterLike, FilterValueSource, Query, QueryConfig, StoreConfig, StoreRecordId } from '@xh/hoist/data';
6
+ import { Cube, Store } from '@xh/hoist/data';
6
7
  import type { ViewRowData } from '@xh/hoist/data/cube/ViewRowData';
7
8
  import { ViewDiagnostics } from './impl/ViewDiagnostics';
8
9
  import { AggregationContext } from './aggregate/AggregationContext';
10
+ import { PivotCells } from './pivot/impl/PivotCells';
9
11
  import { RowCache } from './impl/RowCache';
12
+ import { RowDataGenerator } from './impl/RowDataGenerator';
13
+ import type { PivotCellField, PivotPath } from './pivot/PivotPath';
14
+ import { BaseRow } from './row/BaseRow';
15
+ import type { LeafRow } from './row/LeafRow';
10
16
  import { ExposedLeafRow } from './row/LeafRow';
11
17
  import type { RecordSet, RecordSetDelta } from '../impl/RecordSet';
12
18
  /**
@@ -49,6 +55,43 @@ export interface ViewResult {
49
55
  * safe to publish. Use {@link Cube.store} to read source records directly in that case.
50
56
  */
51
57
  leafMap: Map<StoreRecordId, ExposedLeafRow>;
58
+ /**
59
+ * Pivot path tree, top-level paths first with nested `children`. Empty unless the query sets
60
+ * {@link QueryConfig.pivot}. Identity-stable while the pivot structure is unchanged - track it
61
+ * to decide whether to rebuild columns.
62
+ */
63
+ paths: PivotPath[];
64
+ /**
65
+ * One entry per (pivot path, measure), including the root-path row summaries. Identity-stable
66
+ * with `paths` - track it to decide whether to re-declare Store fields. Note both move on a
67
+ * `measures`-only change, even though the path tree itself is structurally unchanged.
68
+ */
69
+ cellFields: PivotCellField[];
70
+ /**
71
+ * Set when the View declined to produce a result from this data: a step in its pipeline threw
72
+ * a routine `HoistException`, such as the pivot cap in {@link PivotSpec.maxPivotPaths} or an
73
+ * app aggregator rejecting the values it was given. The query is valid and the code is
74
+ * correct, but this data does not fit it, so the message is addressed to the user. `rows`,
75
+ * `paths` and `cellFields` are empty and connected stores are cleared while set. Null
76
+ * otherwise.
77
+ *
78
+ * Any other exception is a bug and propagates from the update that hit it. Mark an exception
79
+ * routine only when the user, not the developer, can clear it.
80
+ */
81
+ exception: HoistException;
82
+ }
83
+ /**
84
+ * Configuration for {@link View.createStore}. Accepts the full {@link StoreConfig} surface,
85
+ * defaulting `loadTreeData` and `projectionOnly` to true.
86
+ * @internal
87
+ */
88
+ export interface ViewStoreConfig extends StoreConfig {
89
+ /**
90
+ * True to register the new Store for live updates from this view. The *caller* owns the store
91
+ * and must call {@link View.disconnectStore} when done with it. False (default) to declare
92
+ * fields and load once from the current result, then never again.
93
+ */
94
+ connect?: boolean;
52
95
  }
53
96
  export interface DimensionValue {
54
97
  /** Dimension field. */
@@ -63,6 +106,10 @@ export interface DimensionValue {
63
106
  *
64
107
  * Use `updateQuery()` to change dimensions, filters, or options dynamically.
65
108
  *
109
+ * A query with {@link QueryConfig.pivot} additionally slices its aggregates across a pivot axis,
110
+ * publishing each cell as a synthetic field on its group row - see {@link ViewResult.cellFields}
111
+ * and `PivotCells`.
112
+ *
66
113
  * See the Cube package README (`data/cube/README.md`) for query patterns and examples
67
114
  * of grand totals, leaf drill-down, and store integration.
68
115
  *
@@ -94,11 +141,15 @@ export declare class View extends HoistBase implements FilterBindTarget, FilterV
94
141
  readonly diagnostics: ViewDiagnostics;
95
142
  _created: number;
96
143
  private _rowDatas;
97
- private _leafMap;
144
+ _rootRows: BaseRow[];
145
+ _leafMap: Map<StoreRecordId, LeafRow>;
98
146
  _records: RecordSet;
99
147
  private _bucketDependentFields;
100
148
  private _fieldsByName;
101
- private _rowDataGenerator;
149
+ private _structuralDimNames;
150
+ _rowDataGenerator: RowDataGenerator;
151
+ _pivot: PivotCells;
152
+ private _ownStores;
102
153
  _aggFieldsByDepth: CubeField[][];
103
154
  _aggFieldNamesByDepth: Set<string>[];
104
155
  _canAggregateFnFieldsByDepth: CubeField[][];
@@ -132,6 +183,21 @@ export declare class View extends HoistBase implements FilterBindTarget, FilterV
132
183
  setStores(stores: Some<Store>): void;
133
184
  /** Update the filter on the current Query.*/
134
185
  setFilter(filter: FilterLike): void;
186
+ /**
187
+ * Create a Store shaped for this view's results - a Field per {@link ViewRowData} member, per
188
+ * query field and, for a pivoted query, per {@link ViewResult.cellFields} entry, kept in sync
189
+ * as the pivot structure changes. `loadRootAsSummary` follows the query's `includeRoot`.
190
+ *
191
+ * The caller owns the returned Store, and with `connect: true` must call
192
+ * {@link disconnectStore} from its own `destroy()`.
193
+ * @internal - used by `CubeGridModel`
194
+ */
195
+ createStore(config?: ViewStoreConfig): Store;
196
+ /**
197
+ * Stop loading the given Store from this view. Callers of {@link createStore} own this call.
198
+ * @internal
199
+ */
200
+ disconnectStore(store: Store): void;
135
201
  noteCubeLoaded(): void;
136
202
  noteCubeUpdated(changes: RecordSetDelta): void;
137
203
  getValuesForFieldFilter(fieldName: string, filter?: Filter): any[];
@@ -150,17 +216,29 @@ export declare class View extends HoistBase implements FilterBindTarget, FilterV
150
216
  * @internal
151
217
  */
152
218
  newLeafRowData(id: string, src: PlainObject): ViewRowData;
219
+ /** Derive the per-query lookup tables. Runs at construction and on every `updateQuery`. */
153
220
  private buildIndices;
154
221
  private fullUpdate;
155
222
  private dataOnlyUpdate;
156
223
  private dataUnchangedUpdate;
224
+ /** Push the rows touched by an incremental update into any connected stores. */
225
+ private loadUpdatedRows;
157
226
  private loadStores;
227
+ /** Load a single store from the current row data, if any has been generated. */
228
+ private loadStore;
158
229
  private updateResults;
230
+ private clearGeneratedRows;
159
231
  private generateRows;
160
232
  private groupAndInsertRecords;
161
233
  private bucketRows;
162
234
  private getSimpleUpdates;
235
+ /**
236
+ * True if any update moves a field that restructures the row hierarchy. `changedFields`, when
237
+ * given, is the producer's assertion of every field touched - if it names nothing structural,
238
+ * no record is examined.
239
+ */
163
240
  private hasDimOrBucketUpdates;
241
+ private hasStructuralChange;
164
242
  private filterRecords;
165
243
  private createAggregationContext;
166
244
  /**
@@ -1,4 +1,5 @@
1
1
  import type { Some } from '@xh/hoist/core';
2
+ import type { FieldSpec } from '@xh/hoist/data';
2
3
  /**
3
4
  * Grouped node data, as returned by {@link Cube.executeQuery} or exposed via {@link View.result}.
4
5
  * Designed for direct consumption by hierarchical stores and their associated tree grids.
@@ -17,6 +18,12 @@ export interface ViewRowData {
17
18
  cubeLabel: string;
18
19
  /** Dimension on which this row was computed, or null for leaf rows. */
19
20
  cubeDimension: string;
21
+ /**
22
+ * Raw, typed value behind {@link cubeLabel} - the dimension or bucket value, or a leaf's record
23
+ * id; null on the root. Bind a tree column's `sortValue` to it so numbers and dates sort by
24
+ * value rather than as text.
25
+ */
26
+ cubeLabelValue: any;
20
27
  /**
21
28
  * Buckets this row appears in
22
29
  */
@@ -41,6 +48,12 @@ export interface ViewRowData {
41
48
  */
42
49
  [key: string]: any;
43
50
  }
51
+ /**
52
+ * Store Field specs for the published members of {@link ViewRowData}. Excludes `id` and
53
+ * `children`, which Store consumes structurally, and `cubeRowDigest`, read as a digest.
54
+ * @internal
55
+ */
56
+ export declare const VIEW_ROW_DATA_FIELDS: FieldSpec[];
44
57
  /**
45
58
  * All visible (i.e. non-locked) cube leaves associated with a row.
46
59
  *
@@ -0,0 +1,19 @@
1
+ import { Aggregator } from './Aggregator';
2
+ /**
3
+ * Takes the median of numeric values across all leaf rows, skipping nulls. Returns null if no leaf
4
+ * has a value.
5
+ *
6
+ * A median cannot be composed from child medians, so each row holds the sorted values beneath it
7
+ * as aggregator state. A full aggregation walks and sorts those values. An update to a leaf moves
8
+ * its value within the sorted values of each ancestor - a binary search, then an array shift
9
+ * linear in the number of values.
10
+ *
11
+ * A row whose `canAggregateFn` returned false contributes its published null, not the leaves
12
+ * beneath it.
13
+ */
14
+ export declare class MedianAggregator extends Aggregator {
15
+ aggregate(rows: any, fieldName: any, context: any): number;
16
+ replace(rows: any, currVal: any, update: any, context: any): any;
17
+ private median;
18
+ private collectValues;
19
+ }
@@ -0,0 +1,30 @@
1
+ import { Aggregator } from './Aggregator';
2
+ /**
3
+ * Sums numeric values across all leaf rows, but only if every leaf with a value shares the same
4
+ * value for a second field - for example, amounts that share a currency. Returns null if those
5
+ * leaves disagree, or if no leaf has a value. Values of the second field are compared by identity,
6
+ * so should be strings, numbers or null - a null counts as a value of its own.
7
+ *
8
+ * Reads the second field from each leaf's source record, so the query need not include it. Not
9
+ * supported where the query groups by the summed field itself - the second field is not checked
10
+ * across those groups.
11
+ *
12
+ * Each row tracks one value of the second field - the most common among its leaves - with a count
13
+ * of the leaves holding it, a count of all leaves with a value, and their total. The row has a
14
+ * single shared value when the two counts are equal. An update to a leaf adjusts these in constant
15
+ * time, except when the last leaf holding the tracked value changes and others remain - the row
16
+ * then walks its leaves to choose a new value to track. A full aggregation also walks the leaves.
17
+ *
18
+ * Create one per field: `{name: 'amount', aggregator: new SumIfSameAggregator('currency')}`.
19
+ */
20
+ export declare class SumIfSameAggregator extends Aggregator {
21
+ readonly matchField: string;
22
+ private readonly _dependsOn;
23
+ constructor(matchField: string);
24
+ get dependsOn(): string[];
25
+ aggregate(rows: any, fieldName: any, context: any): number;
26
+ replace(rows: any, currVal: any, update: any, context: any): any;
27
+ private result;
28
+ private adjust;
29
+ private collect;
30
+ }
@@ -39,6 +39,11 @@ export declare class RowCache {
39
39
  beginGeneration(): void;
40
40
  endGeneration(): void;
41
41
  clear(): void;
42
+ /**
43
+ * Drop cached exposed leaves, whose data objects were minted against a leaf class since
44
+ * rebuilt. Parents are retained and rewired onto the fresh leaves on regeneration.
45
+ */
46
+ invalidateExposedLeaves(): void;
42
47
  private pruneForQueryChange;
43
48
  private removeParentRows;
44
49
  private doEvictUnusedParents;
@@ -18,6 +18,9 @@ import type { ViewRowData } from '../ViewRowData';
18
18
  * generated class per query keeps all leaf datas on a single shape with monomorphic,
19
19
  * inlinable reads.
20
20
  *
21
+ * Pivoted views add two more shapes, driven by `PivotCells` since they track the pivot structure
22
+ * rather than the query alone - see the Pivot section below.
23
+ *
21
24
  * @internal
22
25
  */
23
26
  export declare class RowDataGenerator {
@@ -35,4 +38,27 @@ export declare class RowDataGenerator {
35
38
  private init;
36
39
  private buildParentDataTemplate;
37
40
  private buildLeafDataClass;
41
+ private cellFieldNames;
42
+ private cellAggNames;
43
+ private cellDataTemplate;
44
+ /**
45
+ * Create a cell row's data object from the shared template - the digest slot plus the measures
46
+ * cells aggregate, far narrower than a group row's shape.
47
+ */
48
+ newCellRowData(): PlainObject;
49
+ /** Rebuild the cell template if the measures cells aggregate have moved. */
50
+ onCellAggFieldsChange(): void;
51
+ /**
52
+ * Rebuild the exposed-leaf class if the cell field set has moved, returning true if it did.
53
+ * Called before any leaf is minted in a generation; the caller drops cached leaves on a true.
54
+ */
55
+ onCellFieldsChange(): boolean;
56
+ private cellFieldSignature;
57
+ /**
58
+ * A leaf carries its own value for its full-depth path and every ancestor of it - the one path
59
+ * it belongs to at each depth - and null for the rest, read through prototype getters over one
60
+ * `_pivotPathIdx` slot so every leaf keeps a single hidden class. Root-path cell fields are
61
+ * skipped - their name is the measure's, whose getter already answers.
62
+ */
63
+ private buildPivotLeafDataClass;
38
64
  }
@@ -12,9 +12,13 @@ export declare class ViewDiagnostics extends BaseDiagnostics<View> {
12
12
  accessor load: ViewOpStats;
13
13
  accessor update: ViewOpStats;
14
14
  accessor query: ViewOpStats;
15
+ /** Path discovery and cell build for the last generation of a pivoted view, else null. */
16
+ accessor pivot: PivotOp;
15
17
  noteLoad(type: ViewOp['type'], start: number): void;
16
18
  noteUpdate(type: ViewOp['type'], start: number): void;
17
19
  noteQuery(type: ViewOp['type'], start: number): void;
20
+ /** Note the path discovery and cell build for one generation of a pivoted view. */
21
+ notePivot(op: Omit<PivotOp, 'timestamp'>): void;
18
22
  reset(): void;
19
23
  private note;
20
24
  private accumulate;
@@ -34,3 +38,26 @@ export interface ViewOp {
34
38
  elapsed: number;
35
39
  timestamp: number;
36
40
  }
41
+ export interface PivotOp {
42
+ /** Nodes of the pivot path tree, including the synthetic root path. */
43
+ paths: number;
44
+ /** Cell rows materialized across the whole row hierarchy. */
45
+ cells: number;
46
+ /** Sum of `phases` - all pivot work, excluding base row generation. */
47
+ elapsed: number;
48
+ phases: PivotPhases;
49
+ timestamp: number;
50
+ }
51
+ /** Elapsed ms per phase of one pivot generation. Zero for phases a degenerate build skipped. */
52
+ export interface PivotPhases {
53
+ /** Path discovery over the filtered records, ahead of base row generation. */
54
+ discover: number;
55
+ /** Group enumeration and the per-record leaf alignment pass. */
56
+ align: number;
57
+ /** `buildPivotStructure` - planning the cell set and its links over integer arrays. */
58
+ plan: number;
59
+ /** Cell row instantiation or reuse, wiring, and clearing of vacated cells. */
60
+ build: number;
61
+ /** Projection of cell values onto owner rows. */
62
+ project: number;
63
+ }