@xh/hoist 75.0.0-SNAPSHOT.1752854198386 → 75.0.0-SNAPSHOT.1752860174147

package/CHANGELOG.md

@@ -4,6 +4,12 @@
 
 ### 🎁 New Features
 
+* New property `GridModel.expandToLevel` governs the expansion state of tree and grouped grids.
+  Replaces the use of the `agOptions.groupDefaultExpanded` on the component.
+    * Most recently chosen level is persistable with other grid state.
+    * Default grid context menu has a menu item to trigger bulk expand/collapse to particular depth
+      level for multi-level (e.g. depth > 2) grids.  To enable, implement the `GridModel.levelLabels`
+      property for your grid.
 * Added new `GroupingChooserModel.sortDimensions` config - can be set to false to respect the order
   in which dimensions are provided to the model.
 

package/admin/tabs/activity/tracking/ActivityTrackingModel.ts

@@ -429,6 +429,8 @@ export class ActivityTrackingModel extends HoistModel implements ActivityDetailP
             exportOptions: {filename: exportFilename('activity-summary')},
             emptyText: 'No activity reported...',
             sortBy: ['cubeLabel'],
+            expandToLevel: 1,
+            levelLabels: () => ['Total', ...this.groupingChooserModel.getValueDisplayNames()],
             columns: [
                 {
                     field: {

package/admin/tabs/activity/tracking/ActivityTrackingPanel.ts

@@ -165,10 +165,7 @@ const aggregateView = hoistCmp.factory<ActivityTrackingModel>(({model}) => {
             ]
         }),
         items: [
-            grid({
-                flex: 1,
-                agOptions: {groupDefaultExpanded: 1}
-            }),
+            grid({flex: 1}),
             div({
                 className: 'xh-admin-activity-panel__max-rows-alert',
                 items: [

package/admin/tabs/cluster/objects/ClusterObjectsModel.ts

@@ -43,6 +43,7 @@ export class ClusterObjectsModel extends HoistModel {
     @managed gridModel = new GridModel({
         selModel: 'multiple',
         treeMode: true,
+        expandToLevel: 2,
         autosizeOptions: {mode: 'managed', includeCollapsedChildren: true},
         enableExport: true,
         exportOptions: {filename: exportFilenameWithDate('cluster-objects'), columns: 'ALL'},

package/admin/tabs/cluster/objects/ClusterObjectsPanel.ts

@@ -33,7 +33,7 @@ export const clusterObjectsPanel = hoistCmp.factory({
                         defaultSize: 475,
                         collapsible: false
                     },
-                    item: grid({agOptions: {groupDefaultExpanded: 2}})
+                    item: grid()
                 }),
                 detailPanel()
             ),

package/build/types/cmp/grid/GridContextMenu.d.ts

@@ -12,7 +12,7 @@ export type GridContextMenuItemLike = RecordActionLike | GridContextMenuToken |
  *          `autosizeColumns` - autosize columns to fit their contents.
  *          `copyCell` - copy cell value to clipboard.
  *          `colChooser` - display column chooser for a grid.
- *          `expandCollapseAll` - expand/collapse all parent rows on grouped or tree grid.
+ *          `expandCollapse` - expand/collapse parent rows on grouped or tree grid.
  *          `export` - export grid data to excel via Hoist's server-side export capabilities.
  *          `exportExcel` - alias for `export`.
  *          `exportCsv` - export to CSV via Hoist's server-side export capabilities.
@@ -21,7 +21,7 @@ export type GridContextMenuItemLike = RecordActionLike | GridContextMenuToken |
  *          `restoreDefaults` - restore column, sorting, and grouping configs and clear any
  *              persistent grid state. See {@link GridModel.restoreDefaults}
  */
-export type GridContextMenuToken = 'autosizeColumns' | 'copyCell' | 'colChooser' | 'expandCollapseAll' | 'export' | 'exportExcel' | 'exportCsv' | 'exportLocal' | 'filter' | 'restoreDefaults';
+export type GridContextMenuToken = 'autosizeColumns' | 'copyCell' | 'colChooser' | 'expandCollapseAll' | 'expandCollapse' | 'export' | 'exportExcel' | 'exportCsv' | 'exportLocal' | 'filter' | 'restoreDefaults';
 /**
  * Specification for a GridContextMenu.  Either a list of items, or a function to produce one.
  */

package/build/types/cmp/grid/GridModel.d.ts

@@ -2,7 +2,7 @@ import { CellClickedEvent, CellContextMenuEvent, CellDoubleClickedEvent, ColumnS
 import { AgGridModel } from '@xh/hoist/cmp/ag-grid';
 import { Column, ColumnGroup, ColumnGroupSpec, ColumnSpec, GridAutosizeMode, GridFilterModelConfig, GridGroupSortFn, TreeStyle } from '@xh/hoist/cmp/grid';
 import { GridFilterModel } from '@xh/hoist/cmp/grid/filter/GridFilterModel';
-import { Awaitable, HoistModel, HSide, PlainObject, SizingMode, Some, TaskObserver, VSide } from '@xh/hoist/core';
+import { Awaitable, HoistModel, HSide, PlainObject, SizingMode, Some, TaskObserver, Thunkable, VSide } from '@xh/hoist/core';
 import { Store, StoreConfig, StoreRecord, StoreRecordId, StoreRecordOrId, StoreSelectionConfig, StoreSelectionModel, StoreTransaction } from '@xh/hoist/data';
 import { ExportOptions } from '@xh/hoist/svc/GridExportService';
 import { ReactNode } from 'react';
@@ -54,6 +54,11 @@ export interface GridConfig {
     sortBy?: Some<GridSorterLike>;
     /** Column ID(s) by which to do full-width grouping. */
     groupBy?: Some<string>;
+    /**
+     * Depth level to expand to on initial load. 0 = all collapsed, 1 = top level expanded, etc.
+     * Defaults to 0 for tree grids (i.e. treeMode = true), 1 for standard grouped grids.
+     */
+    expandToLevel?: number;
     /** True (default) to show a count of group member rows within each full-width group row. */
     showGroupRowCounts?: boolean;
     /** Size of text in grid.  If undefined, will default and bind to `XH.sizingMode`. */
@@ -134,6 +139,12 @@ export interface GridConfig {
      * triggered via a long press (aka tap and hold) on mobile devices.
      */
     onCellContextMenu?: (e: CellContextMenuEvent) => void;
+    /**
+     * Array of labels (or a function returning one) that describes the individual depth
+     * levels in a tree or grouped grid. If provided, will be used to construct expand/collapse
+     * options in the default context menu.
+     */
+    levelLabels?: Thunkable<string[]>;
     /**
      * Number of clicks required to expand / collapse a parent row in a tree grid. Defaults
      * to 2 for desktop, 1 for mobile. Any other value prevents clicks on row body from
@@ -240,6 +251,7 @@ export declare class GridModel extends HoistModel {
     onCellClicked: (e: CellClickedEvent) => void;
     onCellDoubleClicked: (e: CellDoubleClickedEvent) => void;
     onCellContextMenu: (e: CellContextMenuEvent) => void;
+    levelLabels: Thunkable<string[]>;
     appData: PlainObject;
     filterModel: GridFilterModel;
     agGridModel: AgGridModel;
@@ -248,6 +260,7 @@ export declare class GridModel extends HoistModel {
     expandState: any;
     sortBy: GridSorter[];
     groupBy: string[];
+    expandToLevel: number;
     get persistableColumnState(): ColumnState[];
     showSummary: boolean | VSide;
     emptyText: ReactNode;
@@ -271,6 +284,7 @@ export declare class GridModel extends HoistModel {
      * To disable autosizing, set autosizeOptions.mode to GridAutosizeMode.DISABLED.
      */
     get autosizeEnabled(): boolean;
+    get maxDepth(): number;
     /** Tracks execution of filtering operations.*/
     filterTask: TaskObserver;
     /** Tracks execution of autosize operations. */
@@ -319,10 +333,15 @@ export declare class GridModel extends HoistModel {
      * will not change the selection if there is already a selection, which is what applications
      * typically want to do when loading/reloading a grid.
      *
-     * @param opts - set key 'ensureVisible' to true to make selection visible if it is within a
-     *      collapsed node or outside of the visible scroll window. Default true.
+     * @param opts -
+     *      expandParentGroups - set to true to expand nodes to allow selection when the
+     *          first selectable node is in a collapsed group. Default true.
+     *      ensureVisible - set to to true to scroll to the selected row if it is outside of the
+     *      visible scroll window. Default true.
+     *
      */
     selectFirstAsync(opts?: {
+        expandParentGroups?: boolean;
         ensureVisible?: boolean;
     }): Promise<void>;
     /**
@@ -414,6 +433,8 @@ export declare class GridModel extends HoistModel {
     expandAll(): void;
     /** Collapse all parent rows in grouped or tree grid. */
     collapseAll(): void;
+    /** Expand all parent rows in grouped or tree grid to the specified level. */
+    setExpandToLevel(level: number): void;
     /**
      * Sort this grid.
      * This method is a no-op if provided any sorters without a corresponding column.

package/build/types/cmp/grid/Types.d.ts

@@ -53,6 +53,8 @@ export interface GridModelPersistOptions extends PersistOptions {
     persistGrouping?: boolean | PersistOptions;
     /** True (default) to include sort state or provide sort-specific PersistOptions. */
     persistSort?: boolean | PersistOptions;
+    /** True (default) to include expanded level state or provide expanded level-specific PersistOptions.  */
+    persistExpandToLevel?: boolean | PersistOptions;
 }
 export interface GridFilterModelConfig {
     /**

package/build/types/cmp/grid/impl/InitPersist.d.ts

@@ -4,4 +4,4 @@ import { GridModelPersistOptions } from '../Types';
  * Initialize persistence for a {@link GridModel} by applying its `persistWith` config.
  * @internal
  */
-export declare function initPersist(gridModel: GridModel, { persistColumns, persistGrouping, persistSort, path, ...rootPersistWith }: GridModelPersistOptions): void;
+export declare function initPersist(gridModel: GridModel, { persistColumns, persistGrouping, persistSort, persistExpandToLevel, path, ...rootPersistWith }: GridModelPersistOptions): void;

package/build/types/cmp/grouping/GroupingChooserModel.d.ts

@@ -78,6 +78,7 @@ export declare class GroupingChooserModel extends HoistModel {
     commitPendingValueAndClose(): void;
     validateValue(value: string[]): boolean;
     getValueLabel(value: string[]): string;
+    getValueDisplayNames(): string[];
     getDimDisplayName(dimName: string): string;
     onDragEnd(result: any): void;
     get favoritesOptions(): {

package/build/types/cmp/zoneGrid/ZoneGridModel.d.ts

@@ -1,6 +1,6 @@
 import { CellClickedEvent, CellContextMenuEvent, CellDoubleClickedEvent, RowClickedEvent, RowDoubleClickedEvent } from '@ag-grid-community/core';
 import { ColumnRenderer, ColumnSpec, GridContextMenuSpec, GridGroupSortFn, GridModel, GridSorter, GridSorterLike, GroupRowRenderer, RowClassFn, RowClassRuleFn, TreeStyle } from '@xh/hoist/cmp/grid';
-import { Awaitable, HoistModel, LoadSpec, PlainObject, Some, VSide } from '@xh/hoist/core';
+import { Awaitable, HoistModel, LoadSpec, PlainObject, Some, Thunkable, VSide } from '@xh/hoist/core';
 import { RecordAction, Store, StoreConfig, StoreRecordOrId, StoreSelectionConfig, StoreSelectionModel, StoreTransaction } from '@xh/hoist/data';
 import { ReactNode } from 'react';
 import { ZoneMapperConfig, ZoneMapperModel } from './impl/ZoneMapperModel';
@@ -72,6 +72,8 @@ export interface ZoneGridConfig {
     sortBy?: GridSorterLike;
     /** Column ID(s) by which to do full-width grouping. */
     groupBy?: Some<string>;
+    /** Group level to expand to on initial load. 0 = all collapsed, 1 = only top level expanded. */
+    expandToLevel?: number;
     /** True (default) to show a count of group member rows within each full-width group row. */
     showGroupRowCounts?: boolean;
     /** True to highlight the currently hovered row. */
@@ -138,6 +140,12 @@ export interface ZoneGridConfig {
      * triggered via a long press (aka tap and hold) on mobile devices.
      */
     onCellContextMenu?: (e: CellContextMenuEvent) => void;
+    /**
+     * Array of labels (or a function returning one) that describes the individual depth
+     * levels in a tree or grouped grid. If provided, will be used to construct expand/collapse
+     * options in the default context menu.
+     */
+    levelLabels?: Thunkable<string[]>;
     /**
      * Number of clicks required to expand / collapse a parent row in a tree grid. Defaults
      * to 2 for desktop, 1 for mobile. Any other value prevents clicks on row body from

package/build/types/data/RecordAction.d.ts

@@ -18,7 +18,7 @@ export interface RecordActionSpec extends TestSupportProps {
     /** Function called on action execution. */
     actionFn?: (data: ActionFnData) => void;
     /** Function called prior to showing this item. */
-    displayFn?: (data: DisplayFnData) => PlainObject;
+    displayFn?: (data: ActionFnData) => RecordActionSpec;
     /** Sub-actions for this action. */
     items?: RecordActionLike[];
     /** True to disable this item. */
@@ -79,7 +79,7 @@ export declare class RecordAction {
     className: string;
     tooltip: string;
     actionFn: (data: ActionFnData) => void;
-    displayFn: (data: DisplayFnData) => PlainObject;
+    displayFn: (data: ActionFnData) => PlainObject;
     items: Array<RecordAction | string>;
     disabled: boolean;
     hidden: boolean;
@@ -108,8 +108,3 @@ export declare class RecordAction {
     call({ record, selectedRecords, gridModel, column, ...rest }: ActionFnData): void;
     private meetsRecordRequirement;
 }
-interface DisplayFnData extends ActionFnData {
-    /** Default display config for the action */
-    defaultConfig?: PlainObject;
-}
-export {};

package/cmp/grid/Grid.ts

@@ -246,7 +246,7 @@ export class GridLocalModel extends HoistModel {
             navigateToNextCell: this.navigateToNextCell,
             processCellForClipboard: this.processCellForClipboard,
             initialGroupOrderComparator: model.groupSortFn ? this.groupSortComparator : undefined,
-            groupDefaultExpanded: 1,
+            groupDefaultExpanded: model.expandToLevel,
             groupDisplayType: 'groupRows',
             groupRowRendererParams: {
                 innerRenderer: model.groupRowRenderer,
@@ -285,7 +285,6 @@ export class GridLocalModel extends HoistModel {
         if (model.treeMode) {
             ret = {
                 ...ret,
-                groupDefaultExpanded: 0,
                 groupDisplayType: 'custom',
                 treeData: true,
                 getDataPath: this.getDataPath

package/cmp/grid/GridContextMenu.ts

@@ -20,7 +20,7 @@ export type GridContextMenuItemLike = RecordActionLike | GridContextMenuToken |
  *          `autosizeColumns` - autosize columns to fit their contents.
  *          `copyCell` - copy cell value to clipboard.
  *          `colChooser` - display column chooser for a grid.
- *          `expandCollapseAll` - expand/collapse all parent rows on grouped or tree grid.
+ *          `expandCollapse` - expand/collapse parent rows on grouped or tree grid.
  *          `export` - export grid data to excel via Hoist's server-side export capabilities.
  *          `exportExcel` - alias for `export`.
  *          `exportCsv` - export to CSV via Hoist's server-side export capabilities.
@@ -34,6 +34,7 @@ export type GridContextMenuToken =
     | 'copyCell'
     | 'colChooser'
     | 'expandCollapseAll'
+    | 'expandCollapse'
     | 'export'
     | 'exportExcel'
     | 'exportCsv'

package/cmp/grid/GridModel.ts

@@ -36,6 +36,7 @@ import {
     SizingMode,
     Some,
     TaskObserver,
+    Thunkable,
     VSide,
     XH
 } from '@xh/hoist/core';
@@ -167,6 +168,12 @@ export interface GridConfig {
     /** Column ID(s) by which to do full-width grouping. */
     groupBy?: Some<string>;
 
+    /**
+     * Depth level to expand to on initial load. 0 = all collapsed, 1 = top level expanded, etc.
+     * Defaults to 0 for tree grids (i.e. treeMode = true), 1 for standard grouped grids.
+     */
+    expandToLevel?: number;
+
     /** True (default) to show a count of group member rows within each full-width group row. */
     showGroupRowCounts?: boolean;
 
@@ -272,6 +279,13 @@ export interface GridConfig {
      */
     onCellContextMenu?: (e: CellContextMenuEvent) => void;
 
+    /**
+     * Array of labels (or a function returning one) that describes the individual depth
+     * levels in a tree or grouped grid. If provided, will be used to construct expand/collapse
+     * options in the default context menu.
+     */
+    levelLabels?: Thunkable<string[]>;
+
     /**
      * Number of clicks required to expand / collapse a parent row in a tree grid. Defaults
      * to 2 for desktop, 1 for mobile. Any other value prevents clicks on row body from
@@ -397,6 +411,7 @@ export class GridModel extends HoistModel {
     onCellClicked: (e: CellClickedEvent) => void;
     onCellDoubleClicked: (e: CellDoubleClickedEvent) => void;
     onCellContextMenu: (e: CellContextMenuEvent) => void;
+    levelLabels: Thunkable<string[]>;
     appData: PlainObject;
 
     @managed filterModel: GridFilterModel;
@@ -410,6 +425,7 @@ export class GridModel extends HoistModel {
     @observable.ref expandState: any = {};
     @observable.ref sortBy: GridSorter[] = [];
     @observable.ref groupBy: string[] = null;
+    @observable expandToLevel: number = 0;
 
     get persistableColumnState(): ColumnState[] {
         return this.cleanColumnState(this.columnState);
@@ -440,7 +456,7 @@ export class GridModel extends HoistModel {
         'copyWithHeaders',
         'copyCell',
         '-',
-        'expandCollapseAll',
+        'expandCollapse',
         '-',
         'exportExcel',
         'exportCsv',
@@ -461,6 +477,11 @@ export class GridModel extends HoistModel {
         return this.autosizeOptions.mode !== 'disabled';
     }
 
+    get maxDepth(): number {
+        const {groupBy, store, treeMode} = this;
+        return treeMode ? store.maxDepth : groupBy ? groupBy.length : 0;
+    }
+
     /** Tracks execution of filtering operations.*/
     @managed filterTask = TaskObserver.trackAll();
 
@@ -518,6 +539,8 @@ export class GridModel extends HoistModel {
             restoreDefaultsWarning = GridModel.DEFAULT_RESTORE_DEFAULTS_WARNING,
             fullRowEditing = false,
             clicksToEdit = 2,
+            expandToLevel = treeMode ? 0 : 1,
+            levelLabels,
             highlightRowOnClick = XH.isMobileApp,
             experimental,
             appData,
@@ -532,7 +555,6 @@ export class GridModel extends HoistModel {
         this.treeMode = treeMode;
         this.treeStyle = treeStyle;
         this.showSummary = showSummary;
-
         this.emptyText = emptyText;
         this.hideEmptyTextBeforeLoad = hideEmptyTextBeforeLoad;
         this.headerMenuDisplay = headerMenuDisplay;
@@ -565,6 +587,8 @@ export class GridModel extends HoistModel {
         this.clicksToExpand = clicksToExpand;
         this.clicksToEdit = clicksToEdit;
         this.highlightRowOnClick = highlightRowOnClick;
+        this.expandToLevel = expandToLevel;
+        this.levelLabels = levelLabels;
 
         throwIf(
             autosizeOptions.fillMode &&
@@ -618,6 +642,13 @@ export class GridModel extends HoistModel {
             debounce: 500
         });
 
+        this.addReaction({
+            track: () => [this.expandToLevel, this.isReady],
+            run: () => {
+                this.agApi?.setGridOption('groupDefaultExpanded', this.expandToLevel);
+            }
+        });
+
         if (!isEmpty(rest)) {
             const keys = keysIn(rest);
             throw XH.exception(
@@ -725,21 +756,29 @@ export class GridModel extends HoistModel {
      * will not change the selection if there is already a selection, which is what applications
      * typically want to do when loading/reloading a grid.
      *
-     * @param opts - set key 'ensureVisible' to true to make selection visible if it is within a
-     *      collapsed node or outside of the visible scroll window. Default true.
+     * @param opts -
+     *      expandParentGroups - set to true to expand nodes to allow selection when the
+     *          first selectable node is in a collapsed group. Default true.
+     *      ensureVisible - set to to true to scroll to the selected row if it is outside of the
+     *      visible scroll window. Default true.
+     *
      */
-    async selectFirstAsync(opts?: {ensureVisible?: boolean}) {
-        const {ensureVisible = true} = opts ?? {};
+    async selectFirstAsync(opts?: {expandParentGroups?: boolean; ensureVisible?: boolean}) {
+        const {expandParentGroups = true, ensureVisible = true} = opts ?? {};
         await this.whenReadyAsync();
         if (!this.isReady) return;
 
-        // Get first displayed row with data - i.e. backed by a record, not a full-width group row.
+        // Get first visible row with data - i.e. backed by a record, not a full-width group row.
         const {selModel} = this,
-            id = this.agGridModel.getFirstSelectableRowNode()?.data.id;
-
-        if (id != null) {
-            selModel.select(id);
-            if (ensureVisible) await this.ensureSelectionVisibleAsync();
+            row = this.agGridModel.getFirstSelectableRowNode();
+
+        // If displayed select it -- we never want to auto-expand parent rows
+        if (row && (expandParentGroups || row.displayed)) {
+            const id = row.data.id;
+            if (id != null) {
+                selModel.select(id);
+                if (ensureVisible) await this.ensureSelectionVisibleAsync();
+            }
         }
     }
 
@@ -749,7 +788,7 @@ export class GridModel extends HoistModel {
      * This method delegates to {@link selectFirstAsync}.
      */
     async preSelectFirstAsync() {
-        if (!this.hasSelection) return this.selectFirstAsync();
+        if (!this.hasSelection) return this.selectFirstAsync({expandParentGroups: false});
     }
 
     /** Deselect all rows. */
@@ -988,20 +1027,18 @@ export class GridModel extends HoistModel {
 
     /** Expand all parent rows in grouped or tree grid. (Note, this is recursive for trees!) */
     expandAll() {
-        const {agApi} = this;
-        if (agApi) {
-            agApi.expandAll();
-            this.noteAgExpandStateChange();
-        }
+        this.setExpandToLevel(this.maxDepth);
     }
 
     /** Collapse all parent rows in grouped or tree grid. */
     collapseAll() {
-        const {agApi} = this;
-        if (agApi) {
-            agApi.collapseAll();
-            this.noteAgExpandStateChange();
-        }
+        this.setExpandToLevel(0);
+    }
+
+    /** Expand all parent rows in grouped or tree grid to the specified level. */
+    @action
+    setExpandToLevel(level: number) {
+        this.expandToLevel = level;
     }
 
     /**

package/cmp/grid/Types.ts

@@ -81,6 +81,8 @@ export interface GridModelPersistOptions extends PersistOptions {
     persistGrouping?: boolean | PersistOptions;
     /** True (default) to include sort state or provide sort-specific PersistOptions. */
     persistSort?: boolean | PersistOptions;
+    /** True (default) to include expanded level state or provide expanded level-specific PersistOptions.  */
+    persistExpandToLevel?: boolean | PersistOptions;
 }
 
 export interface GridFilterModelConfig {

package/cmp/grid/impl/InitPersist.ts

@@ -19,6 +19,7 @@ export function initPersist(
         persistColumns = true,
         persistGrouping = true,
         persistSort = true,
+        persistExpandToLevel = true,
         path = 'grid',
         ...rootPersistWith
     }: GridModelPersistOptions
@@ -75,6 +76,23 @@ export function initPersist(
             owner: gridModel
         });
     }
+
+    if (persistExpandToLevel) {
+        const persistWith = isObject(persistExpandToLevel)
+            ? PersistenceProvider.mergePersistOptions(rootPersistWith, persistExpandToLevel)
+            : rootPersistWith;
+        PersistenceProvider.create({
+            persistOptions: {
+                path: `${path}.expandToLevel`,
+                ...persistWith
+            },
+            target: {
+                getPersistableState: () => new PersistableState(gridModel.expandToLevel),
+                setPersistableState: ({value}) => gridModel.setExpandToLevel(value)
+            },
+            owner: gridModel
+        });
+    }
 }
 
 class PersistableColumnState extends PersistableState<ColumnState[]> {

package/cmp/grid/impl/MenuSupport.ts

@@ -9,6 +9,7 @@ import {Column, GridModel} from '@xh/hoist/cmp/grid';
 import {RecordAction, Store, StoreRecord} from '@xh/hoist/data';
 import {convertIconToHtml, Icon} from '@xh/hoist/icon';
 import {filterConsecutiveMenuSeparators} from '@xh/hoist/utils/impl';
+import {executeIfFunction} from '@xh/hoist/utils/js';
 import copy from 'clipboard-copy';
 import {isEmpty, isFunction, isNil, isString, uniq} from 'lodash';
 import {isValidElement} from 'react';
@@ -136,21 +137,9 @@ function replaceHoistToken(token: string, gridModel: GridModel): Some<RecordActi
                 hidden: !gridModel?.colChooserModel,
                 actionFn: () => (gridModel.colChooserModel as any)?.open()
             });
-        case 'expandCollapseAll':
-            return [
-                new RecordAction({
-                    text: 'Expand All',
-                    icon: Icon.groupRowExpanded(),
-                    hidden: !gridModel || (!gridModel.treeMode && isEmpty(gridModel.groupBy)),
-                    actionFn: () => gridModel.expandAll()
-                }),
-                new RecordAction({
-                    text: 'Collapse All',
-                    icon: Icon.groupRowCollapsed(),
-                    hidden: !gridModel || (!gridModel.treeMode && isEmpty(gridModel.groupBy)),
-                    actionFn: () => gridModel.collapseAll()
-                })
-            ];
+        case 'expandCollapseAll': // For backward compatibility
+        case 'expandCollapse':
+            return createExpandCollapseItem(gridModel);
         case 'export':
         case 'exportExcel':
             return new RecordAction({
@@ -270,3 +259,53 @@ function replaceHoistToken(token: string, gridModel: GridModel): Some<RecordActi
             return token;
     }
 }
+
+function createExpandCollapseItem(gridModel: GridModel): RecordAction[] {
+    if (!gridModel || gridModel.maxDepth === 0) return null;
+
+    return [
+        new RecordAction({
+            text: 'Expand All',
+            icon: Icon.groupRowExpanded(),
+            actionFn: () => gridModel.expandAll()
+        }),
+        new RecordAction({
+            text: 'Collapse All',
+            icon: Icon.groupRowCollapsed(),
+            actionFn: () => gridModel.collapseAll()
+        }),
+        levelExpandAction(gridModel)
+    ];
+}
+
+function levelExpandAction(gridModel: GridModel): RecordAction {
+    return new RecordAction({
+        text: 'Expand to ...',
+        displayFn: () => {
+            // Don't show for degenerate shallow grid models, or if we don't have labels
+            const {maxDepth, expandToLevel} = gridModel;
+            if (maxDepth <= 1) return {hidden: true};
+
+            const levelLabels = executeIfFunction(gridModel.levelLabels);
+            if (!levelLabels || levelLabels.length < maxDepth + 1) {
+                gridModel.logDebug(
+                    '"levelLabels" not provided or of insufficient length. No menu items shown.'
+                );
+                return {hidden: true};
+            }
+
+            const items = levelLabels.map((label, idx) => {
+                const isCurrLevel =
+                    expandToLevel === idx ||
+                    (expandToLevel > maxDepth && idx === levelLabels.length - 1);
+
+                return {
+                    icon: isCurrLevel ? Icon.check() : null,
+                    text: label,
+                    actionFn: () => gridModel.setExpandToLevel(idx)
+                };
+            });
+            return {items};
+        }
+    });
+}

package/cmp/grouping/GroupingChooserModel.ts

@@ -274,6 +274,10 @@ export class GroupingChooserModel extends HoistModel {
         return value.map(dimName => this.getDimDisplayName(dimName)).join(' › ');
     }
 
+    getValueDisplayNames(): string[] {
+        return this.value.map(dimName => this.getDimDisplayName(dimName));
+    }
+
     getDimDisplayName(dimName: string) {
         return this.dimensions[dimName]?.displayName ?? dimName;
     }

package/cmp/zoneGrid/ZoneGridModel.ts

@@ -39,6 +39,7 @@ import {
     managed,
     PlainObject,
     Some,
+    Thunkable,
     VSide,
     XH
 } from '@xh/hoist/core';
@@ -146,6 +147,9 @@ export interface ZoneGridConfig {
     /** Column ID(s) by which to do full-width grouping. */
     groupBy?: Some<string>;
 
+    /** Group level to expand to on initial load. 0 = all collapsed, 1 = only top level expanded. */
+    expandToLevel?: number;
+
     /** True (default) to show a count of group member rows within each full-width group row. */
     showGroupRowCounts?: boolean;
 
@@ -231,6 +235,13 @@ export interface ZoneGridConfig {
      */
     onCellContextMenu?: (e: CellContextMenuEvent) => void;
 
+    /**
+     * Array of labels (or a function returning one) that describes the individual depth
+     * levels in a tree or grouped grid. If provided, will be used to construct expand/collapse
+     * options in the default context menu.
+     */
+    levelLabels?: Thunkable<string[]>;
+
     /**
      * Number of clicks required to expand / collapse a parent row in a tree grid. Defaults
      * to 2 for desktop, 1 for mobile. Any other value prevents clicks on row body from
@@ -419,7 +430,7 @@ export class ZoneGridModel extends HoistModel {
         'copyWithHeaders',
         'copyCell',
         '-',
-        'expandCollapseAll',
+        'expandCollapse',
         '-',
         'restoreDefaults',
         '-',