@xh/hoist 78.0.0-SNAPSHOT.1763665705643 → 78.0.0-SNAPSHOT.1763737348746

package/CHANGELOG.md

@@ -4,14 +4,17 @@
 
 ### 💥 Breaking Changes
 
-* `GridModel.cleanColumnState` is now private (not expected to impact applications).
 * `GridModel.setColumnState` no longer patches existing column state, but instead replaces it
   wholesale. Applications that were relying on the prior patching behavior will need to
   call `GridModel.applyColumnStateChanges` instead.
+* `GridModel.cleanColumnState` is now private (not expected to impact applications).
 
 ### 🎁 New Features
 
-* `FieldFilter` implementation expanded to support `not begins` and `not ends` operators.
+* Added new `FieldFilter` operators `not begins` and `not ends`.
+* Added new optional `BucketSpec.dependentFields` config to the Cube API, allowing apps to ensure
+  proper re-bucketing of rows during data-only updates where those updates could affect bucketing
+  determinations made by the spec.
 
 ### 🐞 Bug Fixes
 
@@ -19,11 +22,15 @@
   numerical ID.
 * Fixed issue where newly added columns appearing in the Displayed Columns section of the column
   chooser after loading grid state that was persisted before the columns were added to the grid.
+* Removed a minor Cube `Query` annoyance - `dimensions` are now automatically added to the `fields`
+  list and do not need to be manually repeated there.
 
 ### ⚙️ Technical
 
-* `FetchService` will recognize variants on the `application/json` content-type when processing
-  failed responses and decoding exceptions - e.g. `application/problem+json`.
+* Updated the Cube API's `BucketSpecFn` to return either a concrete `BucketSpec` class instance (as
+  before) or a plain object conforming to the new `BucketSpecConfig` interface.
+* Enhanced `FetchService` to recognize variants on the `application/json` content-type when
+  processing failed responses and decoding exceptions - e.g. `application/problem+json`.
 
 ## 77.1.1 - 2025-11-12
 

package/build/types/data/cube/BucketSpec.d.ts

@@ -1,16 +1,36 @@
 import { BaseRow } from './row/BaseRow';
 /**
- * @see BucketSpecFn
+ * Spec to define a bucketing level within the hierarchy of data returned by a Query, as identified
+ * by a set of rows passed to a {@link BucketSpecFn} configured on that Query (or defaulted from
+ * the Cube). If this object is returned for a candidate set of rows, each row is evaluated by the
+ * spec's `bucketFn` to determine if it should yield a value for the bucket, causing the row to be
+ * nested underneath a new {@link BucketRow} created to hold all rows with that value.
  */
+export interface BucketSpecConfig {
+    /** Name for the bucketing level configured by this spec - equivalent to a dimension name. */
+    name: string;
+    /**
+     * Function returning the bucketed value (if any) into which the given row should be placed -
+     * equivalent to a dimension value. Return null/undefined to exclude the row from bucketing.
+     */
+    bucketFn: (row: BaseRow) => string;
+    /**
+     * Function returning bucket row label from the bucket value string returned by bucketFn.
+     * Defaults to using the value directly.
+     */
+    labelFn?: (bucket: string) => string;
+    /**
+     * Fields on which the `bucketFn` depends, to ensure rows are re-bucketed if dependent field
+     * values change. If not provided or does not cover all fields potentially accessed by
+     * `bucketFn`, an incremental "data only" update that should have changed a row's bucket can
+     * fail to do so.
+     */
+    dependentFields?: string[];
+}
 export declare class BucketSpec {
     name: string;
     bucketFn: (row: BaseRow) => string;
     labelFn: (bucket: string) => string;
-    /**
-     * @param name - name of bucket.
-     * @param bucketFn - function to determine which (if any) bucket the given row should
-     *      be placed into
-     * @param labelFn - function to generate the bucket row label from name returned by bucketFn
-     **/
-    constructor(name: string, bucketFn: (row: BaseRow) => string, labelFn?: (bucket: string) => string);
+    dependentFields: string[];
+    constructor(config: BucketSpecConfig);
 }

package/build/types/data/cube/Cube.d.ts

@@ -8,7 +8,7 @@ import { StoreRecord } from '../StoreRecord';
 import { AggregateRow } from './row/AggregateRow';
 import { BucketRow } from './row/BucketRow';
 import { BaseRow } from './row/BaseRow';
-import { BucketSpec } from './BucketSpec';
+import { BucketSpec, BucketSpecConfig } from './BucketSpec';
 export interface CubeConfig {
     fields: CubeField[] | CubeFieldSpec[];
     /** Default configs applied to all `CubeField`s constructed internally by this Cube. */
@@ -60,9 +60,9 @@ export type OmitFn = (row: AggregateRow | BucketRow) => boolean;
  * aggregations and create an unwanted "Open" grouping.
  *
  * @param rows - the rows being checked for bucketing
- * @returns BucketSpec for configuring dynamic sub-aggregations, or null to perform no bucketing.
+ * @returns {@link BucketSpecConfig} for dynamic sub-aggregations, or null to perform no bucketing.
  */
-export type BucketSpecFn = (rows: BaseRow[]) => BucketSpec;
+export type BucketSpecFn = (rows: BaseRow[]) => BucketSpecConfig | BucketSpec;
 /**
  * A data store that supports grouping, aggregating, and filtering data on multiple dimensions.
  *

package/build/types/data/cube/Query.d.ts

@@ -19,8 +19,6 @@ export interface QueryConfig {
      * Fields or field names on which data should be grouped and aggregated. These are the ordered
      * grouping levels in the resulting hierarchy - e.g. ['Country', 'State', 'City'].
      *
-     * Any fields provided here must also be included in the `fields` array, if specified.
-     *
      * If not provided or empty, the resulting data will not be grouped. Specify 'includeRoot' or
      * 'includeLeaves' in that case, otherwise no data will be returned.
      */
@@ -81,7 +79,7 @@ export interface QueryConfig {
      *
      * This can be used to break selected aggregations into sub-groups dynamically, without having
      * to define another dimension in the Cube and have it apply to all aggregations. See the
-     * {@link BucketSpecFn} type and {@link BucketSpec} interface for additional information.
+     * {@link BucketSpecFn} type and {@link BucketSpecConfig} interface for additional information.
      *
      * Defaults to {@link Cube.bucketSpecFn}.
      */

package/build/types/data/cube/View.d.ts

@@ -1,5 +1,5 @@
 import { HoistBase, PlainObject, Some } from '@xh/hoist/core';
-import { Cube, CubeField, Filter, FilterLike, Query, QueryConfig, Store, StoreRecordId } from '@xh/hoist/data';
+import { Cube, CubeField, Filter, FilterLike, Query, QueryConfig, Store, StoreChangeLog, StoreRecordId } from '@xh/hoist/data';
 import { ViewRowData } from '@xh/hoist/data/cube/ViewRowData';
 import { AggregationContext } from './aggregate/AggregationContext';
 import { BaseRow } from './row/BaseRow';
@@ -51,6 +51,7 @@ export declare class View extends HoistBase {
     private _rowDatas;
     private _leafMap;
     private _recordMap;
+    private _bucketDependentFields;
     _aggContext: AggregationContext;
     _rowCache: Map<string, BaseRow>;
     /** @internal - applications should use {@link Cube.createView} */
@@ -79,7 +80,7 @@ export declare class View extends HoistBase {
     /** Update the filter on the current Query.*/
     setFilter(filter: FilterLike): void;
     noteCubeLoaded(): void;
-    noteCubeUpdated(changeLog: PlainObject): void;
+    noteCubeUpdated(changeLog: StoreChangeLog): void;
     private fullUpdate;
     private dataOnlyUpdate;
     private loadStores;
@@ -88,7 +89,7 @@ export declare class View extends HoistBase {
     private groupAndInsertRecords;
     private bucketRows;
     private getSimpleUpdates;
-    private hasDimUpdates;
+    private hasDimOrBucketUpdates;
     private cachedRow;
     private filterRecords;
     private createAggregationContext;

package/build/types/data/cube/row/BucketRow.d.ts

@@ -5,7 +5,7 @@ import { View } from '../View';
 /**
  *  Row within a dataset produced by a Cube / View representing aggregated data on a dimension that
  *  has been further grouped into a dynamic child "bucket" - a subset of the dimension-level
- *  {@link AggregateRow} produced as per a specified {@link Query.bucketSpecFn}.
+ *  {@link AggregateRow} produced as per a specified {@link BucketSpecFn}.
  *
  * This is an internal data structure - {@link ViewRowData} is the public row-level data API.
  */

package/data/cube/BucketSpec.ts

@@ -8,26 +8,44 @@
 import {BaseRow} from './row/BaseRow';
 
 /**
- * @see BucketSpecFn
+ * Spec to define a bucketing level within the hierarchy of data returned by a Query, as identified
+ * by a set of rows passed to a {@link BucketSpecFn} configured on that Query (or defaulted from
+ * the Cube). If this object is returned for a candidate set of rows, each row is evaluated by the
+ * spec's `bucketFn` to determine if it should yield a value for the bucket, causing the row to be
+ * nested underneath a new {@link BucketRow} created to hold all rows with that value.
  */
+export interface BucketSpecConfig {
+    /** Name for the bucketing level configured by this spec - equivalent to a dimension name. */
+    name: string;
+    /**
+     * Function returning the bucketed value (if any) into which the given row should be placed -
+     * equivalent to a dimension value. Return null/undefined to exclude the row from bucketing.
+     */
+    bucketFn: (row: BaseRow) => string;
+    /**
+     * Function returning bucket row label from the bucket value string returned by bucketFn.
+     * Defaults to using the value directly.
+     */
+    labelFn?: (bucket: string) => string;
+    /**
+     * Fields on which the `bucketFn` depends, to ensure rows are re-bucketed if dependent field
+     * values change. If not provided or does not cover all fields potentially accessed by
+     * `bucketFn`, an incremental "data only" update that should have changed a row's bucket can
+     * fail to do so.
+     */
+    dependentFields?: string[];
+}
+
 export class BucketSpec {
     name: string;
     bucketFn: (row: BaseRow) => string;
     labelFn: (bucket: string) => string;
+    dependentFields: string[];
 
-    /**
-     * @param name - name of bucket.
-     * @param bucketFn - function to determine which (if any) bucket the given row should
-     *      be placed into
-     * @param labelFn - function to generate the bucket row label from name returned by bucketFn
-     **/
-    constructor(
-        name: string,
-        bucketFn: (row: BaseRow) => string,
-        labelFn?: (bucket: string) => string
-    ) {
-        this.name = name;
-        this.bucketFn = bucketFn;
-        this.labelFn = labelFn ?? (b => b);
+    constructor(config: BucketSpecConfig) {
+        this.name = config.name;
+        this.bucketFn = config.bucketFn;
+        this.labelFn = config.labelFn ?? (b => b);
+        this.dependentFields = config.dependentFields ?? [];
     }
 }

package/data/cube/Cube.ts

@@ -17,7 +17,7 @@ import {StoreRecord} from '../StoreRecord';
 import {AggregateRow} from './row/AggregateRow';
 import {BucketRow} from './row/BucketRow';
 import {BaseRow} from './row/BaseRow';
-import {BucketSpec} from './BucketSpec';
+import {BucketSpec, BucketSpecConfig} from './BucketSpec';
 import {defaultsDeep, isEmpty} from 'lodash';
 
 export interface CubeConfig {
@@ -82,9 +82,9 @@ export type OmitFn = (row: AggregateRow | BucketRow) => boolean;
  * aggregations and create an unwanted "Open" grouping.
  *
  * @param rows - the rows being checked for bucketing
- * @returns BucketSpec for configuring dynamic sub-aggregations, or null to perform no bucketing.
+ * @returns {@link BucketSpecConfig} for dynamic sub-aggregations, or null to perform no bucketing.
  */
-export type BucketSpecFn = (rows: BaseRow[]) => BucketSpec;
+export type BucketSpecFn = (rows: BaseRow[]) => BucketSpecConfig | BucketSpec;
 
 /**
  * A data store that supports grouping, aggregating, and filtering data on multiple dimensions.

package/data/cube/Query.ts

@@ -16,7 +16,7 @@ import {
     StoreRecord
 } from '@xh/hoist/data';
 import {throwIf} from '@xh/hoist/utils/js';
-import {find, isEqual} from 'lodash';
+import {find, isEqual, uniq} from 'lodash';
 import {Cube} from './Cube';
 import {CubeField} from './CubeField';
 
@@ -40,8 +40,6 @@ export interface QueryConfig {
      * Fields or field names on which data should be grouped and aggregated. These are the ordered
      * grouping levels in the resulting hierarchy - e.g. ['Country', 'State', 'City'].
      *
-     * Any fields provided here must also be included in the `fields` array, if specified.
-     *
      * If not provided or empty, the resulting data will not be grouped. Specify 'includeRoot' or
      * 'includeLeaves' in that case, otherwise no data will be returned.
      */
@@ -109,7 +107,7 @@ export interface QueryConfig {
      *
      * This can be used to break selected aggregations into sub-groups dynamically, without having
      * to define another dimension in the Cube and have it apply to all aggregations. See the
-     * {@link BucketSpecFn} type and {@link BucketSpec} interface for additional information.
+     * {@link BucketSpecFn} type and {@link BucketSpecConfig} interface for additional information.
      *
      * Defaults to {@link Cube.bucketSpecFn}.
      */
@@ -153,8 +151,8 @@ export class Query {
         omitFn = cube.omitFn
     }: QueryConfig) {
         this.cube = cube;
-        this.fields = this.parseFields(fields);
         this.dimensions = this.parseDimensions(dimensions);
+        this.fields = uniq([...this.parseFields(fields), ...(this.dimensions ?? [])]);
         this.includeRoot = includeRoot;
         this.includeLeaves = includeLeaves;
         this.provideLeaves = provideLeaves;
@@ -234,7 +232,7 @@ export class Query {
     private parseDimensions(raw: CubeField[] | string[]): CubeField[] {
         if (!raw) return null;
         if (raw[0] instanceof CubeField) return raw as CubeField[];
-        const {fields} = this;
+        const {fields} = this.cube;
         return raw.map(name => {
             const field = find(fields, {name});
             throwIf(

package/data/cube/View.ts

@@ -14,14 +14,16 @@ import {
     Query,
     QueryConfig,
     Store,
+    StoreChangeLog,
     StoreRecord,
     StoreRecordId
 } from '@xh/hoist/data';
+import {BucketSpec} from '@xh/hoist/data/cube/BucketSpec';
 import {ViewRowData} from '@xh/hoist/data/cube/ViewRowData';
 import {action, makeObservable, observable} from '@xh/hoist/mobx';
 import {shallowEqualArrays} from '@xh/hoist/utils/impl';
 import {logWithDebug, throwIf} from '@xh/hoist/utils/js';
-import {castArray, find, forEach, groupBy, isEmpty, isNil, map} from 'lodash';
+import {castArray, find, forEach, groupBy, isEmpty, isNil, map, uniq} from 'lodash';
 import {AggregationContext} from './aggregate/AggregationContext';
 import {AggregateRow} from './row/AggregateRow';
 import {BaseRow} from './row/BaseRow';
@@ -94,6 +96,7 @@ export class View extends HoistBase {
     private _rowDatas: ViewRowData[] = null;
     private _leafMap: Map<StoreRecordId, LeafRow> = null;
     private _recordMap: Map<StoreRecordId, StoreRecord> = null;
+    private _bucketDependentFields = new Set<string>();
     _aggContext: AggregationContext = null;
     _rowCache: Map<string, BaseRow> = null;
 
@@ -207,7 +210,7 @@ export class View extends HoistBase {
     }
 
     @action
-    noteCubeUpdated(changeLog: PlainObject) {
+    noteCubeUpdated(changeLog: StoreChangeLog) {
         const simpleUpdates = this.getSimpleUpdates(changeLog);
 
         if (!simpleUpdates) {
@@ -277,6 +280,8 @@ export class View extends HoistBase {
             {dimensions, includeRoot} = query,
             rootId = 'root';
 
+        this._bucketDependentFields.clear();
+
         const records = this._aggContext.filteredRecords;
         const leafMap: Map<StoreRecordId, LeafRow> = new Map();
         let newRows = this.groupAndInsertRecords(records, dimensions, rootId, {}, leafMap);
@@ -360,13 +365,19 @@ export class View extends HoistBase {
         if (!query.bucketSpecFn) return rows;
         if (!query.includeLeaves && rows[0]?.isLeaf) return rows;
 
-        const bucketSpec = query.bucketSpecFn(rows);
-        if (!bucketSpec) return rows;
+        const bucketSpecOrConf = query.bucketSpecFn(rows);
+        if (!bucketSpecOrConf) return rows;
 
-        const {name: bucketName, bucketFn} = bucketSpec,
+        const bucketSpec =
+            bucketSpecOrConf instanceof BucketSpec
+                ? bucketSpecOrConf
+                : new BucketSpec(bucketSpecOrConf);
+        const {name: bucketName, bucketFn, dependentFields} = bucketSpec,
             buckets: Record<string, BaseRow[]> = {},
             ret: BaseRow[] = [];
 
+        dependentFields.forEach(it => this._bucketDependentFields.add(it));
+
         // Determine which bucket to put this row into (if any)
         rows.forEach(row => {
             const bucketVal = bucketFn(row);
@@ -394,14 +405,14 @@ export class View extends HoistBase {
 
     // return a list of simple data updates we can apply to leaves.
     // false if leaf population changing, or aggregations are complex
-    private getSimpleUpdates(t): StoreRecord[] | false {
+    private getSimpleUpdates(t: StoreChangeLog): StoreRecord[] | false {
         if (!t) return [];
         if (!this.aggregatorsAreSimple) return false;
         const {_leafMap, query} = this;
 
         // 1) Simple case: no filter
         if (!query.filter) {
-            return isEmpty(t.add) && isEmpty(t.remove) && !this.hasDimUpdates(t.update)
+            return isEmpty(t.add) && isEmpty(t.remove) && !this.hasDimOrBucketUpdates(t.update)
                 ? t.update
                 : false;
         }
@@ -425,19 +436,21 @@ export class View extends HoistBase {
 
         // 2c) Examine the final set of updates for any changes to dimension field values which would
         //     require rebuilding the row hierarchy
-        if (this.hasDimUpdates(ret)) return false;
+        if (this.hasDimOrBucketUpdates(ret)) return false;
 
         return ret;
     }
 
-    private hasDimUpdates(update: StoreRecord[]): boolean {
-        const {dimensions} = this.query;
-        if (isEmpty(dimensions)) return false;
+    private hasDimOrBucketUpdates(update: StoreRecord[]): boolean {
+        const {dimensions} = this.query,
+            bucketDependentFields = Array.from(this._bucketDependentFields);
+
+        if (isEmpty(dimensions) && isEmpty(bucketDependentFields)) return false;
 
-        const dimNames = dimensions.map(it => it.name);
+        const fieldNames = uniq([...dimensions.map(it => it.name), ...bucketDependentFields]);
         for (const rec of update) {
             const curRec = this._leafMap.get(rec.id);
-            if (dimNames.some(name => rec.data[name] !== curRec.data[name])) return true;
+            if (fieldNames.some(name => rec.data[name] !== curRec.data[name])) return true;
         }
 
         return false;

package/data/cube/row/BucketRow.ts

@@ -13,7 +13,7 @@ import {View} from '../View';
 /**
  *  Row within a dataset produced by a Cube / View representing aggregated data on a dimension that
  *  has been further grouped into a dynamic child "bucket" - a subset of the dimension-level
- *  {@link AggregateRow} produced as per a specified {@link Query.bucketSpecFn}.
+ *  {@link AggregateRow} produced as per a specified {@link BucketSpecFn}.
  *
  * This is an internal data structure - {@link ViewRowData} is the public row-level data API.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xh/hoist",
-  "version": "78.0.0-SNAPSHOT.1763665705643",
+  "version": "78.0.0-SNAPSHOT.1763737348746",
   "description": "Hoist add-on for building and deploying React Applications.",
   "repository": "github:xh/hoist-react",
   "homepage": "https://xh.io",