@xh/hoist 83.1.0 → 84.0.1

package/data/README.md

@@ -1,5 +1,19 @@
 # Data Package
 
+| Section | Description |
+|---------|-------------|
+| [Overview](#overview) | Core classes, architecture diagram |
+| [Store](#store) | Creating, loading, filtering, and observing record collections |
+| [StoreRecord](#storerecord) | Record state, data access, tree navigation, validation |
+| [Field](#field) | Type parsing, display names, descriptions, validation rules |
+| [Filter System](#filter-system) | FieldFilter, CompoundFilter, FunctionFilter, and utilities |
+| [Validation System](#validation-system) | Rules, constraints, severity levels, async validation |
+| [Integration with GridModel](#integration-with-gridmodel) | Inline store config, data loading, and editing |
+| [Tree Data](#tree-data) | Hierarchical loading, filtering, and summary records |
+| [Cube (Aggregation)](#cube-aggregation) | Pointer to dedicated [`cube/README.md`](cube/README.md) |
+| [Common Patterns](#common-patterns) | Record reuse, processRawData, composite IDs |
+| [Common Pitfalls](#common-pitfalls) | ID fields, missing IDs, data mutation, FunctionFilter persistence |
+
 ## Overview
 
 The `/data/` package provides Hoist's data management layer - observable, in-memory data containers
@@ -603,6 +617,36 @@ record.errors;                     // Map<field, string[]>
 record.validationResults;          // Map<field, ValidationResult[]>
 ```
 
+## Integration with GridModel
+
+Stores are the primary data source for GridModel:
+
+```typescript
+import {GridModel} from '@xh/hoist/cmp/grid';
+import {numberEditor} from '@xh/hoist/desktop/cmp/grid';
+
+const gridModel = new GridModel({
+    // Inline store config
+    store: {
+        fields: [
+            {name: 'name', type: 'string'},
+            {name: 'salary', type: 'number', rules: [required]}
+        ]
+    },
+    columns: [
+        {field: 'name', flex: 1},
+        {field: 'salary', width: 120, editable: true, editor: numberEditor()}
+    ]
+});
+
+// Load data through GridModel (delegates to store)
+gridModel.loadData(data);
+
+// Access store directly
+gridModel.store.records;
+gridModel.store.setFilter({field: 'salary', op: '>', value: 50000});
+```
+
 ## Tree Data
 
 Stores provide full support for hierarchical parent-child data.
@@ -690,130 +734,10 @@ See `cmp/grid/GridModel.ts` for details on summary row rendering.
 
 ## Cube (Aggregation)
 
-**Files**: `cube/Cube.ts`, `cube/CubeField.ts`, `cube/Query.ts`, `cube/View.ts`
-
-Multi-dimensional aggregation for OLAP-style grouping and analysis.
-
-### Creating a Cube
-
-```typescript
-import {Cube} from '@xh/hoist/data';
-
-const cube = new Cube({
-    fields: [
-        // Dimensions - can be grouped on
-        {name: 'region', isDimension: true},
-        {name: 'product', isDimension: true},
-        {name: 'year', isDimension: true},
-
-        // Measures - aggregated values
-        {name: 'revenue', aggregator: 'SUM'},
-        {name: 'quantity', aggregator: 'SUM'},
-        {name: 'avgPrice', aggregator: 'AVG'}
-    ]
-});
-
-await cube.loadDataAsync(salesData);
-```
-
-### Built-in Aggregators
-
-| Aggregator | Description |
-|------------|-------------|
-| `'SUM'` | Total of non-null values |
-| `'SUM_STRICT'` | Total only if all non-null |
-| `'AVG'` | Average of non-null values |
-| `'AVG_STRICT'` | Average only if all non-null |
-| `'MIN'` | Minimum value |
-| `'MAX'` | Maximum value |
-| `'UNIQUE'` | Count of unique values |
-| `'LEAF_COUNT'` | Count of leaf records |
-| `'CHILD_COUNT'` | Count of immediate children |
-
-### Querying and Accessing View Data
-
-```typescript
-// Create a view with specific groupings
-const view = cube.createView({
-    query: {
-        cube,
-        dimensions: ['region', 'product'],
-        filter: {field: 'year', op: '=', value: 2024},
-        includeLeaves: false,
-        includeRoot: true
-    },
-    connect: true  // Auto-update when cube data changes
-});
-```
-
-There are two primary ways to access view data:
-
-**Option 1: Read `view.result` directly**
-
-The observable `ViewResult` contains hierarchical `ViewRowData` objects:
-
-```typescript
-// React to view updates
-addReaction({
-    track: () => view.result,
-    run: (result) => {
-        const {rows, leafMap} = result;
-        // rows: ViewRowData[] - hierarchical aggregated data
-        // leafMap: Map<id, LeafRow> - direct access to leaf-level rows
-    }
-});
-```
-
-**Option 2: Connect stores for automatic loading**
-
-Provide one or more stores that the view will automatically populate:
-
-```typescript
-const store = new Store({fields: [...]});
-
-const view = cube.createView({
-    query: {...},
-    stores: store,   // View auto-loads data into this store
-    connect: true
-});
-
-// Store now receives updates automatically
-gridModel.store === store;  // Use with GridModel
-```
-
-**Update triggers:** View data updates when either:
-- The underlying Cube data changes (requires `connect: true`)
-- The `view.query` is modified via `view.updateQuery()`
-
-## Integration with GridModel
-
-Stores are the primary data source for GridModel:
-
-```typescript
-import {GridModel} from '@xh/hoist/cmp/grid';
-import {numberEditor} from '@xh/hoist/desktop/cmp/grid';
-
-const gridModel = new GridModel({
-    // Inline store config
-    store: {
-        fields: [
-            {name: 'name', type: 'string'},
-            {name: 'salary', type: 'number', rules: [required]}
-        ]
-    },
-    columns: [
-        {field: 'name', flex: 1},
-        {field: 'salary', width: 120, editable: true, editor: numberEditor()}
-    ]
-});
-
-// Load data through GridModel (delegates to store)
-gridModel.loadData(data);
-
-// Access store directly
-gridModel.store.records;
-gridModel.store.setFilter({field: 'salary', op: '>', value: 50000});
-```
+Client-side OLAP-style aggregation for multi-dimensional grouping and analysis. The Cube
+subsystem has its own dedicated documentation — see the
+[Cube package README](cube/README.md) for full coverage of creating Cubes, aggregators,
+querying with Views, and accessing results.
 
 ## Common Patterns
 

package/data/Store.ts

@@ -47,6 +47,20 @@ import {
 import {instanceManager} from '../core/impl/InstanceManager';
 import {RecordSet} from './impl/RecordSet';
 
+/**
+ * Configuration for a {@link Store}. At minimum, provide `fields` (or let them be inferred
+ * from GridModel columns). Data can be supplied at construction via `data`, or loaded later
+ * via `Store.loadData()`.
+ *
+ * Can also be passed inline as the `store` config on {@link GridConfig}, where it will be
+ * used to construct a Store automatically.
+ *
+ * See the data package README (`data/README.md`) for tree data, filtering, validation, and
+ * performance tuning guidance.
+ *
+ * @see Store
+ * @see FieldSpec
+ */
 export interface StoreConfig {
     /** Field names, configs, or instances. */
     fields?: Array<string | FieldSpec | Field>;
@@ -203,7 +217,27 @@ export interface ChildRawData {
 export type StoreRecordIdSpec = string | ((data: PlainObject) => StoreRecordId);
 
 /**
- * A managed and observable set of local, in-memory Records.
+ * A managed, observable collection of in-memory {@link StoreRecord}s - the core data container
+ * in Hoist. Used directly by applications and as the data source for {@link GridModel},
+ * {@link DataViewModel}, and other data-bound components.
+ *
+ * Stores provide:
+ * - Observable record collections with filtering via composable {@link Filter} objects
+ * - Hierarchical/tree data with parent-child navigation
+ * - Local modification tracking (add/modify/remove) with commit/revert
+ * - Record reuse across data reloads to preserve grid row state
+ * - Pluggable validation via {@link Field} rules
+ *
+ * Data is loaded via `loadData()` (full replacement) or `updateData()` (transactional). Fields
+ * can be defined explicitly or inferred from GridModel columns. `Store.defaults` provides
+ * app-wide configuration.
+ *
+ * See the data package README (`data/README.md`) for full documentation including tree data,
+ * filtering patterns, validation, and common pitfalls.
+ *
+ * @see StoreConfig
+ * @see StoreRecord
+ * @see Field
  */
 export class Store
     extends HoistBase

package/data/StoreSelectionModel.ts

@@ -11,15 +11,31 @@ import {castArray, compact, remove, isEqual, union, map} from 'lodash';
 import {Store} from './Store';
 import {StoreRecord, StoreRecordId, StoreRecordOrId} from './StoreRecord';
 
+/**
+ * Configuration for a {@link StoreSelectionModel}. Typically passed via the `selModel` config
+ * on {@link GridConfig} rather than constructed directly.
+ *
+ * @see StoreSelectionModel
+ */
 export interface StoreSelectionConfig {
     store?: Store;
     mode?: 'single' | 'multiple' | 'disabled';
+    /** @internal */
     xhImpl?: boolean;
 }
 
 /**
- * Model for managing store selections.
- * Typically accessed from a GridModel to observe/control Grid selection.
+ * Model for managing record selection within a {@link Store}. Supports `single`, `multiple`,
+ * and `disabled` modes.
+ *
+ * Typically accessed via `gridModel.selModel` rather than created directly - configure via
+ * the `selModel` property on {@link GridConfig}.
+ *
+ * Key observables for reacting to selection state: `selectedRecord` / `selectedRecords`
+ * (reactive to both identity and data changes), `selectedId` / `selectedIds` (identity only),
+ * `isEmpty`, `count`. Use `select()` and `clear()` for programmatic control.
+ *
+ * @see StoreSelectionConfig
  */
 export class StoreSelectionModel extends HoistModel {
     readonly store: Store;

package/data/cube/Cube.ts

@@ -20,6 +20,16 @@ import {BucketRow} from './row/BucketRow';
 import {View} from './View';
 import {ViewRowData} from './ViewRowData';
 
+/**
+ * Configuration for a {@link Cube}. Provide `fields` (including at least one dimension
+ * and one or more measures with aggregators) and load data via `data` or
+ * `Cube.loadDataAsync()`.
+ *
+ * See the Cube package README (`data/cube/README.md`) for aggregator options and usage patterns.
+ *
+ * @see Cube
+ * @see CubeFieldSpec
+ */
 export interface CubeConfig {
     fields: CubeField[] | CubeFieldSpec[];
 
@@ -87,13 +97,23 @@ export type OmitFn = (row: AggregateRow | BucketRow) => boolean;
 export type BucketSpecFn = (rows: BaseRow[]) => BucketSpec;
 
 /**
- * A data store that supports grouping, aggregating, and filtering data on multiple dimensions.
+ * Client-side OLAP-style data structure for multi-dimensional grouping and aggregation.
+ *
+ * A Cube wraps a flat {@link Store} of leaf-level records and supports creating {@link View}s
+ * via structured {@link Query} objects. Each View filters, groups, and aggregates the source
+ * data into a hierarchical result for use in tree grids, treemaps, and other visualizations.
+ *
+ * Fields are defined as {@link CubeField}s - each marked as either a dimension (groupable)
+ * or a measure with an {@link Aggregator} (e.g. SUM, AVG, MIN, MAX). Views can be transient
+ * (run a query once) or connected for efficient, auto-updating results as source data changes.
+ *
+ * See the Cube package README (`data/cube/README.md`) for full documentation including
+ * aggregator options, querying patterns, and View integration with Store/GridModel.
  *
- * This object is a wrapper around a "flat" Store containing leaf-level facts. It supports creating
- * Views on that data via structured Queries that can filter, group, and aggregate the flat source
- * data and produce a hierarchical result ready for use in (e.g.) tree grids and maps. Views can
- * be transiently created to run a Query once, on demand, or can be retained to provide efficient,
- * auto-updating results in response to updates to the underlying data.
+ * @see CubeConfig
+ * @see CubeField
+ * @see View
+ * @see Query
  */
 export class Cube extends HoistBase {
     static RECORD_ID_DELIMITER = '>>';

package/data/cube/Query.ts

@@ -22,6 +22,16 @@ import {CubeField} from './CubeField';
 
 /**
  * Queries determine what data is extracted, grouped, and aggregated from a {@link Cube}.
+ * Passed via the `query` property of {@link ViewConfig} when creating a View.
+ *
+ * Key options beyond `dimensions` and `filter`: `includeRoot` adds a grand-total row,
+ * `includeLeaves` exposes source records as tree children, and `provideLeaves` makes them
+ * accessible programmatically without rendering in the tree.
+ *
+ * See the Cube package README (`data/cube/README.md#querying-with-views`) for query patterns.
+ *
+ * @see Cube
+ * @see View
  */
 export interface QueryConfig {
     /**

package/data/cube/README.md

@@ -0,0 +1,236 @@
+# Cube Package
+
+| Section | Description |
+|---------|-------------|
+| [Overview](#overview) | Architecture, dimensions vs. measures, CubeField configuration |
+| [Creating a Cube](#creating-a-cube) | Field definitions, data loading |
+| [Built-in Aggregators](#built-in-aggregators) | SUM, AVG, MIN, MAX, and counting aggregators |
+| [Querying with Views](#querying-with-views) | Grouped queries, grand totals, leaf drill-down, dynamic updates |
+| [Accessing View Data](#accessing-view-data) | Connected stores vs. direct result access |
+
+## Overview
+
+The `/data/cube/` package provides a client-side OLAP-style aggregation engine. A `Cube` wraps
+a flat collection of leaf-level records and supports creating `View`s via structured `Query`
+objects that filter, group, and aggregate the source data into hierarchical results.
+
+| Class | Purpose |
+|-------|---------|
+| **Cube** | Aggregation engine holding source data and creating Views |
+| **CubeField** | Field metadata extending `Field` with dimension/aggregator config |
+| **Query** | Immutable specification of dimensions, filters, and output options |
+| **View** | Observable query result, optionally auto-updating connected Stores |
+
+Fields are defined as `CubeField`s — each marked as either a **dimension** (groupable category)
+or a **measure** with an `Aggregator` (e.g. SUM, AVG). Views produce hierarchical results ready
+for use in tree grids, treemaps, and other visualizations.
+
+For the core data layer (Store, Field, Filter, Validation), see the
+[data package README](../README.md).
+
+## Creating a Cube
+
+```typescript
+import {Cube} from '@xh/hoist/data';
+
+const cube = new Cube({
+    fields: [
+        // Dimensions - can be grouped on
+        {name: 'region', isDimension: true},
+        {name: 'product', isDimension: true},
+        {name: 'year', isDimension: true},
+
+        // Measures - aggregated values
+        {name: 'revenue', aggregator: 'SUM'},
+        {name: 'quantity', aggregator: 'SUM'},
+        {name: 'avgPrice', aggregator: 'AVG'}
+    ]
+});
+
+await cube.loadDataAsync(salesData);
+```
+
+## Built-in Aggregators
+
+| Aggregator | Description |
+|------------|-------------|
+| `'SUM'` | Total of non-null values |
+| `'SUM_STRICT'` | Total only if all non-null |
+| `'AVG'` | Average of non-null values |
+| `'AVG_STRICT'` | Average only if all non-null |
+| `'MIN'` | Minimum value |
+| `'MAX'` | Maximum value |
+| `'UNIQUE'` | Count of unique values |
+| `'LEAF_COUNT'` | Count of leaf records |
+| `'CHILD_COUNT'` | Count of immediate children |
+
+## Querying with Views
+
+Views are the primary interface for consuming Cube data. Create them via `Cube.createView()`
+with a `QueryConfig` specifying dimensions, filters, and output options.
+
+**Basic grouped query:**
+
+```typescript
+const view = cube.createView({
+    query: {
+        dimensions: ['region', 'product'],
+        filter: {field: 'year', op: '=', value: 2024}
+    },
+    stores: store,
+    connect: true  // Auto-update when cube data changes
+});
+```
+
+This produces a hierarchy of aggregated rows: Region → Product, with measures (revenue,
+quantity) summed at each level. Only aggregate rows are returned — leaf-level source records
+are excluded by default.
+
+**Grand totals with `includeRoot`:**
+
+```typescript
+// Include a synthetic root node with grand totals across all data.
+// Pairs with GridConfig.showSummary and StoreConfig.loadRootAsSummary
+// to display a docked total row in grids.
+const view = cube.createView({
+    query: {
+        dimensions: ['region', 'product'],
+        includeRoot: true
+    },
+    stores: new Store({loadRootAsSummary: true}),
+    connect: true
+});
+
+// The connected GridModel can then show the root as a summary row:
+const gridModel = new GridModel({store, showSummary: true, ...});
+```
+
+**Leaf-level drill-down with `includeLeaves`:**
+
+```typescript
+// Include the original source records as children of the lowest
+// aggregation level — users can expand groups to see underlying facts.
+const view = cube.createView({
+    query: {
+        dimensions: ['region'],
+        includeLeaves: true
+    },
+    stores: store,
+    connect: true
+});
+// In a tree grid, expanding "North America" shows its aggregated children,
+// and expanding those shows the individual source records.
+```
+
+**Programmatic leaf access with `provideLeaves`:**
+
+```typescript
+// Like includeLeaves, but leaves are accessible programmatically via
+// ViewRowData.cubeLeaves rather than rendered as tree children.
+// Useful for showing detail in a separate panel on selection.
+const view = cube.createView({
+    query: {
+        dimensions: ['region', 'product'],
+        provideLeaves: true
+    },
+    stores: store,
+    connect: true
+});
+```
+
+**Flat aggregation (no dimensions):**
+
+```typescript
+// No dimensions — just filter and aggregate. Must specify includeRoot
+// or includeLeaves, otherwise no data will be returned.
+const view = cube.createView({
+    query: {
+        includeRoot: true,   // Single row with grand totals
+        filter: {field: 'region', op: '=', value: 'EMEA'}
+    },
+    stores: store,
+    connect: true
+});
+```
+
+**Updating queries dynamically:**
+
+```typescript
+// Change dimensions, filters, or options on an existing View.
+// Connected stores are automatically refreshed.
+view.updateQuery({
+    dimensions: ['product', 'region'],  // Swap grouping order
+    filter: {field: 'year', op: '=', value: 2025}
+});
+
+// Shorthand for filter-only updates:
+view.setFilter({field: 'year', op: '=', value: 2025});
+```
+
+**One-shot queries with `executeQuery`:**
+
+For cases where you need aggregated data once without retaining a View — e.g. computing a
+summary for a tooltip or populating a one-time report — use `Cube.executeQuery()` directly.
+This creates a transient View internally, extracts the results, and destroys it immediately:
+
+```typescript
+// Returns ViewRowData[] directly — no View to manage or destroy.
+const rows = cube.executeQuery({
+    dimensions: ['region'],
+    includeRoot: true,
+    filter: {field: 'year', op: '=', value: 2024}
+});
+
+// Use the rows directly — e.g. extract the root for a grand total
+const grandTotal = rows.find(r => r.isRoot);
+```
+
+Use `createView()` when you need connected auto-updates or store integration;
+use `executeQuery()` for lightweight, fire-and-forget queries.
+
+## Accessing View Data
+
+There are two ways to consume View results:
+
+**Option 1: Connected stores (recommended for grids)**
+
+Provide one or more stores via `ViewConfig.stores`. The View auto-loads hierarchical data
+into them whenever the query results change:
+
+```typescript
+const store = new Store({fields: [...]});
+
+const view = cube.createView({
+    query: {dimensions: ['region', 'product']},
+    stores: store,
+    connect: true
+});
+
+// Use the store with a GridModel
+const gridModel = new GridModel({store, treeMode: true, columns: [...]});
+```
+
+**Option 2: Read `view.result` directly**
+
+The observable `ViewResult` contains hierarchical `ViewRowData` objects:
+
+```typescript
+addReaction({
+    track: () => view.result,
+    run: (result) => {
+        const {rows, leafMap} = result;
+        // rows: ViewRowData[] - hierarchical aggregated data
+        // leafMap: Map<id, LeafRow> - direct access to leaf-level rows
+    }
+});
+```
+
+**Update triggers:** View data updates when either:
+- The underlying Cube data changes (requires `connect: true`)
+- The `view.query` is modified via `view.updateQuery()`
+
+## Related Packages
+
+- [`/data/`](../README.md) - Store, Field, Filter, Validation - the core data layer
+- [`/cmp/grid/`](../../cmp/grid/README.md) - GridModel consumes Store for data display
+- `/cmp/grouping/` - GroupingChooser for specifying multi-level dimension groupings

package/data/cube/View.ts

@@ -32,6 +32,15 @@ import {BaseRow} from './row/BaseRow';
 import {BucketRow} from './row/BucketRow';
 import {LeafRow} from './row/LeafRow';
 
+/**
+ * Configuration for a {@link View} - a query result from a {@link Cube} that can optionally
+ * stay connected for live updates. Create via {@link Cube.createView}.
+ *
+ * See the Cube package README (`data/cube/README.md`) for query patterns.
+ *
+ * @see View
+ * @see QueryConfig
+ */
 export interface ViewConfig {
     /** Query to be used to construct this view. */
     query: Query;
@@ -64,8 +73,18 @@ export interface DimensionValue {
 }
 
 /**
- * Primary interface for consuming grouped and aggregated data from the cube.
- * Applications should create via the {@link Cube.createView} factory.
+ * Primary interface for consuming grouped and aggregated data from a {@link Cube}.
+ * Created via {@link Cube.createView} with a {@link QueryConfig} and optional connected
+ * stores. Views can be transient (run once) or connected for auto-updating results.
+ *
+ * Use `updateQuery()` to change dimensions, filters, or options dynamically.
+ *
+ * See the Cube package README (`data/cube/README.md`) for query patterns and examples
+ * of grand totals, leaf drill-down, and store integration.
+ *
+ * @see ViewConfig
+ * @see QueryConfig
+ * @see Cube
  */
 export class View
     extends HoistBase

package/data/cube/aggregate/Aggregator.ts

@@ -10,6 +10,19 @@ import {BaseRow} from '../row/BaseRow';
 import {LeafRow} from '../row/LeafRow';
 import {RowUpdate} from '../row/RowUpdate';
 
+/**
+ * Abstract base class for Cube field aggregation functions.
+ *
+ * Subclasses implement {@link aggregate} to compute a summary value for a set of rows, and
+ * may optionally override {@link replace} to efficiently update the aggregation when a single
+ * child row changes (the default re-aggregates from scratch).
+ *
+ * Standard implementations are provided for common operations: sum, average, min, max,
+ * unique, count, and null. Custom aggregators can extend this class for application-specific
+ * aggregation logic.
+ *
+ * @see CubeField.aggregator
+ */
 export abstract class Aggregator {
     /**
      * Does this aggregator depend only on leaf nodes contained by the node being aggregated?

package/data/cube/aggregate/AverageAggregator.ts

@@ -7,6 +7,7 @@
 
 import {Aggregator} from './Aggregator';
 
+/** Averages numeric values across all leaf rows, skipping nulls. */
 export class AverageAggregator extends Aggregator {
     override aggregate(rows, fieldName) {
         let total = null,

package/data/cube/aggregate/AverageStrictAggregator.ts

@@ -7,6 +7,7 @@
 
 import {Aggregator} from './Aggregator';
 
+/** Averages numeric values, returning null if any leaf value is null. */
 export class AverageStrictAggregator extends Aggregator {
     override aggregate(rows, fieldName) {
         let total = null,

package/data/cube/aggregate/ChildCountAggregator.ts

@@ -7,6 +7,7 @@
 
 import {Aggregator} from './Aggregator';
 
+/** Returns the count of direct child rows. */
 export class ChildCountAggregator extends Aggregator {
     override aggregate(rows, fieldName) {
         return rows.length;

package/data/cube/aggregate/LeafCountAggregator.ts

@@ -7,6 +7,7 @@
 
 import {Aggregator} from './Aggregator';
 
+/** Returns the count of all leaf (non-aggregate) descendant rows. */
 export class LeafCountAggregator extends Aggregator {
     override aggregate(rows, fieldName) {
         let count = 0;

package/data/cube/aggregate/MaxAggregator.ts

@@ -7,6 +7,7 @@
 
 import {Aggregator} from './Aggregator';
 
+/** Returns the maximum value across rows, skipping nulls. */
 export class MaxAggregator extends Aggregator {
     override aggregate(rows, fieldName) {
         return rows.reduce((ret, it) => {

package/data/cube/aggregate/MinAggregator.ts

@@ -7,6 +7,7 @@
 
 import {Aggregator} from './Aggregator';
 
+/** Returns the minimum value across rows, skipping nulls. */
 export class MinAggregator extends Aggregator {
     override aggregate(rows, fieldName) {
         return rows.reduce((ret, it) => {