@xh/hoist 75.0.0-SNAPSHOT.1753116344421 → 75.0.0-SNAPSHOT.1753279912670

package/CHANGELOG.md

@@ -9,8 +9,13 @@
     * The most recently expanded level is persistable with other grid state.
     * The default grid context menu now supports a new item to allow users to expand/collapse out to
       a specific level/depth. Set `GridModel.levelLabels` to activate this feature.
+    * A new `ExpandToLevelButton` menu component is also available for both desktop and mobile.
+      Provides easier discoverability on desktop and supports this feature on mobile, where we
+      don't have context menus.
 * Added new `GroupingChooserModel.sortDimensions` config. Set to `false` to respect the order in
   which `dimensions` are provided to the model.
+* The usage of the `RelativeTimestamp` component has been streamlined by deprecating the `options`
+  prop.  All `RelativeTimestampOptions` are now supported by this component as top-level props.
 
 ### 🐞 Bug Fixes
 

package/admin/tabs/clients/activity/ClientDetailPanel.ts

@@ -40,11 +40,12 @@ const clientDetail = hoistCmp.factory<ClientDetailModel>(({model}) => {
                         items: [
                             relativeTimestamp({
                                 timestamp: data.createdTime,
-                                options: {prefix: 'Session established'}
+                                prefix: 'Session established'
                             }),
                             relativeTimestamp({
                                 timestamp: data.lastReceivedTime,
-                                options: {prefix: 'Last heartbeat', emptyResult: 'No heartbeat yet'}
+                                prefix: 'Last heartbeat',
+                                emptyResult: 'No heartbeat yet'
                             })
                         ]
                     })

package/admin/tabs/general/alertBanner/AlertBannerPanel.ts

@@ -148,11 +148,8 @@ const formPanel = hoistCmp.factory<AlertBannerModel>(({model}) => {
                             field: 'expires',
                             info: relativeTimestamp({
                                 timestamp: formModel.values.expires,
-                                options: {
-                                    allowFuture: true,
-                                    emptyResult:
-                                        'Set a date & time to automatically hide this banner.'
-                                }
+                                allowFuture: true,
+                                emptyResult: 'Set a date & time to automatically hide this banner.'
                             }),
                             item: dateInput({
                                 enableClear: true,

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

@@ -143,7 +143,8 @@ export interface GridConfig {
      * Array of strings (or a function returning one) providing user-facing labels for each depth
      * level in a tree or grouped grid - e.g. `['Country', 'State', 'City']`. If set, the
      * expand/collapse options in the default context menu will be enhanced to allow users to
-     * expand/collapse to a specific level.
+     * expand/collapse to a specific level. See {@link GroupingChooserModel.valueDisplayNames}
+     * for a convenient getter that will satisfy this API when a GroupingChooser is in play.
      */
     levelLabels?: Thunkable<string[]>;
     /**

package/build/types/cmp/relativetimestamp/RelativeTimestamp.d.ts

@@ -1,5 +1,5 @@
 import { BoxProps, HoistProps } from '@xh/hoist/core';
-interface RelativeTimestampProps extends HoistProps, BoxProps {
+interface RelativeTimestampProps extends HoistProps, BoxProps, RelativeTimestampOptions {
     /**
      * Property on context model containing timestamp.
      * Specify as an alternative to direct `timestamp` prop (and minimize parent re-renders).
@@ -7,7 +7,11 @@ interface RelativeTimestampProps extends HoistProps, BoxProps {
     bind?: string;
     /** Date or milliseconds representing the starting time / time to compare. See also `bind`. */
     timestamp?: Date | number;
-    /** Formatting options */
+    /**
+     * Formatting options.
+     *
+     * @deprecated - these options should be spread into this object directly.
+     */
     options?: RelativeTimestampOptions;
 }
 export interface RelativeTimestampOptions {

package/build/types/desktop/cmp/button/{ColAutosizeButton.d.ts → grid/ColAutosizeButton.d.ts}

@@ -1,8 +1,8 @@
-import { GridModel, GridAutosizeOptions } from '@xh/hoist/cmp/grid';
+import { GridAutosizeOptions, GridModel } from '@xh/hoist/cmp/grid';
 import '@xh/hoist/desktop/register';
-import { ButtonProps } from './Button';
+import { ButtonProps } from '../Button';
 export interface ColAutosizeButtonProps extends ButtonProps {
-    /** GridModel of the grid for which this button should autosize columns. */
+    /** GridModel to which this button should bind. Will find nearest in context if not provided. */
     gridModel?: GridModel;
     /** Options for the grid autosize. */
     autosizeOptions?: Omit<GridAutosizeOptions, 'mode'>;

package/build/types/desktop/cmp/button/{ColChooserButton.d.ts → grid/ColChooserButton.d.ts}

@@ -1,9 +1,9 @@
 import { GridModel } from '@xh/hoist/cmp/grid';
 import '@xh/hoist/desktop/register';
 import { Position } from '@xh/hoist/kit/blueprint';
-import { ButtonProps } from './Button';
+import { ButtonProps } from '../Button';
 export interface ColChooserButtonProps extends ButtonProps {
-    /** GridModel of the grid for which this button should show a chooser. */
+    /** GridModel to which this button should bind. Will find nearest in context if not provided. */
     gridModel?: GridModel;
     /** Position for chooser popover, as per Blueprint docs. */
     popoverPosition?: Position;
@@ -13,6 +13,6 @@ export interface ColChooserButtonProps extends ButtonProps {
  * available Grid columns. For use by applications when a button is desired in addition to the
  * context menu item built into the Grid component directly.
  *
- * Requires the `GridModel.colChooserModel` config option. Set to true for default implementation.
+ * Requires {@link GridConfig.colChooserModel} to be configured on the bound GridModel.
  */
 export declare const ColChooserButton: import("react").FC<ColChooserButtonProps>, colChooserButton: import("@xh/hoist/core").ElementFactory<ColChooserButtonProps>;

package/build/types/desktop/cmp/button/grid/ExpandToLevelButton.d.ts

@@ -0,0 +1,18 @@
+import { GridModel } from '@xh/hoist/cmp/grid';
+import '@xh/hoist/desktop/register';
+import { Position } from '@xh/hoist/kit/blueprint';
+import { ReactNode } from 'react';
+import { ButtonProps } from '../Button';
+export interface ExpandToLevelButtonProps extends Omit<ButtonProps, 'title'> {
+    /** GridModel to which this button should bind. Will find nearest in context if not provided. */
+    gridModel?: GridModel;
+    /** Position for menu, as per Blueprint docs. */
+    popoverPosition?: Position;
+    /** Title for the menu popover - defaults to "Expand To Level". */
+    title: ReactNode;
+}
+/**
+ * A menu button to expand a multi-level grouped or tree grid out to a desired level.
+ * Requires {@link GridConfig.levelLabels} to be configured on the bound GridModel.
+ */
+export declare const ExpandToLevelButton: import("react").FC<ExpandToLevelButtonProps>, expandToLevelButton: import("@xh/hoist/core").ElementFactory<ExpandToLevelButtonProps>;

package/build/types/desktop/cmp/button/{ExportButton.d.ts → grid/ExportButton.d.ts}

@@ -1,21 +1,21 @@
 import { GridModel } from '@xh/hoist/cmp/grid';
 import '@xh/hoist/desktop/register';
 import { ExportOptions } from '@xh/hoist/svc';
-import { ButtonProps } from './Button';
+import { ButtonProps } from '../Button';
 export interface ExportButtonProps extends ButtonProps {
+    /** GridModel to which this button should bind. Will find nearest in context if not provided. */
     gridModel?: GridModel;
     exportOptions?: ExportOptions;
 }
 /**
  * Convenience Button preconfigured for use as a trigger for an export/download of data.
  *
- * Must be provided either an onClick handler *or* a gridModel.  GridModel may be provided
- * in props, or otherwise will be looked up by this model from context.
+ * Must be provided either an onClick handler *or* a gridModel. GridModel may be provided via props,
+ * otherwise will be looked up by this model from context.
  *
- * If a gridModel is provided, this button will call exportAsync() on the model class.
- * Options supported by GridExportService.exportAsync() can be set via the exportOptions
- * props.
+ * If a GridModel is provided, this button will call {@link GridModel.exportAsync}. The grid's
+ * {@link ExportOptions} will be used unless overridden via this component's `exportOptions` prop.
  *
- * Requires the `GridModel.enableExport` config option to be true.
+ * Requires {@link GridConfig.enableExport} option to be true on the bound GridModel.
  */
 export declare const ExportButton: import("react").FC<ExportButtonProps>, exportButton: import("@xh/hoist/core").ElementFactory<ExportButtonProps>;

package/build/types/desktop/cmp/button/index.d.ts

@@ -1,16 +1,17 @@
-export * from './Button';
 export * from './AppMenuButton';
+export * from './Button';
 export * from './ButtonGroup';
-export * from './ColAutosizeButton';
-export * from './ColChooserButton';
 export * from './DashCanvasAddViewButton';
-export * from './ExportButton';
 export * from './FeedbackButton';
 export * from './LaunchAdminButton';
 export * from './LogoutButton';
-export * from './ModalToggleButton';
+export * from './panel/ModalToggleButton';
 export * from './OptionsButton';
 export * from './RefreshButton';
 export * from './RestoreDefaultsButton';
 export * from './ThemeToggleButton';
-export * from './ZoneMapperButton';
+export * from './grid/ColAutosizeButton';
+export * from './grid/ColChooserButton';
+export * from './grid/ExpandToLevelButton';
+export * from './grid/ExportButton';
+export * from './zoneGrid/ZoneMapperButton';

package/build/types/desktop/cmp/button/{ZoneMapperButton.d.ts → zoneGrid/ZoneMapperButton.d.ts}

@@ -1,16 +1,15 @@
 import '@xh/hoist/desktop/register';
 import { ZoneGridModel } from '@xh/hoist/cmp/zoneGrid';
 import { Position } from '@xh/hoist/kit/blueprint';
-import { ButtonProps } from './Button';
+import { ButtonProps } from '../Button';
 export interface ZoneMapperButtonProps extends ButtonProps {
-    /** ZoneGridModel of the grid for which this button should show a chooser. */
+    /** ZoneGridModel to which this button should bind. Will find nearest in context if not provided. */
     zoneGridModel?: ZoneGridModel;
     /** Position for chooser popover, as per Blueprint docs. */
     popoverPosition?: Position;
 }
 /**
  * A convenience button to trigger the display of a ZoneMapper UI for ZoneGrid configuration.
- *
- * Requires a `ZoneGridModel.zoneMapperModel` config option, set to true for default implementation.
+ * Requires {@link ZoneGridConfig.zoneMapperModel} to be configured on the bound ZoneGridModel.
  */
 export declare const ZoneMapperButton: import("react").FC<ZoneMapperButtonProps>, zoneMapperButton: import("@xh/hoist/core").ElementFactory<ZoneMapperButtonProps>;

package/build/types/mobile/cmp/button/{ColAutosizeButton.d.ts → grid/ColAutosizeButton.d.ts}

@@ -2,9 +2,9 @@ import { GridModel, GridAutosizeOptions } from '@xh/hoist/cmp/grid';
 import { ButtonProps } from '@xh/hoist/mobile/cmp/button';
 import '@xh/hoist/mobile/register';
 export interface ColAutosizeButtonProps extends ButtonProps {
-    /** GridModel of the grid for which this button should autosize columns. */
+    /** GridModel to which this button should bind. Will find nearest in context if not provided. */
     gridModel?: GridModel;
-    /** Options for the grid autosize. */
+    /** Options to override grid's default or configured autosize settings. */
     autosizeOptions?: Omit<GridAutosizeOptions, 'mode'>;
 }
 /**

package/build/types/mobile/cmp/button/{ColChooserButton.d.ts → grid/ColChooserButton.d.ts}

@@ -2,13 +2,13 @@ import { GridModel } from '@xh/hoist/cmp/grid';
 import { ButtonProps } from '@xh/hoist/mobile/cmp/button';
 import '@xh/hoist/mobile/register';
 export interface ColChooserButtonProps extends ButtonProps {
-    /** GridModel of the grid for which this button should show a chooser. */
+    /** GridModel to which this button should bind. Will find nearest in context if not provided. */
     gridModel?: GridModel;
 }
 /**
- * A convenience button to trigger the display of a ColChooser for user selection,
- * discovery and reordering of available Grid columns.
+ * A convenience button to trigger the display of a ColChooser for user selection, discovery and
+ * reordering of available Grid columns.
  *
- * Requires a `GridModel.colChooserModel` config option, set to true for default implementation.
+ * Requires {@link GridConfig.colChooserModel} to be configured on the bound GridModel.
  */
 export declare const ColChooserButton: import("react").FC<ColChooserButtonProps>, colChooserButton: import("@xh/hoist/core").ElementFactory<ColChooserButtonProps>;

package/build/types/mobile/cmp/button/{ExpandCollapseButton.d.ts → grid/ExpandCollapseButton.d.ts}

@@ -2,10 +2,13 @@ import { GridModel } from '@xh/hoist/cmp/grid';
 import { ButtonProps } from '@xh/hoist/mobile/cmp/button';
 import '@xh/hoist/mobile/register';
 export interface ExpandCollapseButtonProps extends ButtonProps {
-    /** GridModel of the grid for which this button should show a chooser. */
+    /**
+     * `GridModel` to which this button should bind.
+     * Optional, will find nearest GridModel in context if not provided.
+     */
     gridModel?: GridModel;
 }
 /**
- * A convenience button to expand / collapse all rows in grouped or tree grid.
+ * A convenience button to expand / collapse all rows in a grouped or tree Grid.
  */
 export declare const ExpandCollapseButton: import("react").FC<ExpandCollapseButtonProps>, expandCollapseButton: import("@xh/hoist/core").ElementFactory<ExpandCollapseButtonProps>;

package/build/types/mobile/cmp/button/grid/ExpandToLevelButton.d.ts

@@ -0,0 +1,15 @@
+import { GridModel } from '@xh/hoist/cmp/grid';
+import '@xh/hoist/mobile/register';
+import { MenuButtonProps } from '../../menu';
+export interface ExpandToLevelButtonProps extends MenuButtonProps {
+    /**
+     * `GridModel` to which this button should bind.
+     * Optional, will find nearest GridModel in context if not provided.
+     */
+    gridModel?: GridModel;
+}
+/**
+ * A menu button to expand a multi-level grouped or tree grid out to a desired level.
+ * Requires {@link GridConfig.levelLabels} to be configured on the bound GridModel.
+ */
+export declare const ExpandToLevelButton: import("react").FC<ExpandToLevelButtonProps>, expandToLevelButton: import("@xh/hoist/core").ElementFactory<ExpandToLevelButtonProps>;

package/build/types/mobile/cmp/button/index.d.ts

@@ -1,12 +1,13 @@
 export * from './Button';
 export * from './ButtonGroup';
-export * from './ColAutosizeButton';
-export * from './ColChooserButton';
-export * from './ExpandCollapseButton';
+export * from './grid/ColAutosizeButton';
+export * from './grid/ColChooserButton';
+export * from './grid/ExpandCollapseButton';
+export * from './grid/ExpandToLevelButton';
 export * from './FeedbackButton';
 export * from './ThemeToggleButton';
 export * from './LogoutButton';
 export * from './RefreshButton';
 export * from './RestoreDefaultsButton';
 export * from './NavigatorBackButton';
-export * from './ZoneMapperButton';
+export * from './zoneGrid/ZoneMapperButton';

package/build/types/mobile/cmp/button/{ZoneMapperButton.d.ts → zoneGrid/ZoneMapperButton.d.ts}

@@ -1,5 +1,5 @@
-import { ZoneGridModel } from '../../../cmp/zoneGrid';
 import { ButtonProps } from '@xh/hoist/mobile/cmp/button';
+import { ZoneGridModel } from '@xh/hoist/cmp/zoneGrid';
 import '@xh/hoist/mobile/register';
 export interface ZoneMapperButtonProps extends ButtonProps {
     /** ZoneGridModel of the grid for which this button should show a chooser. */
@@ -7,7 +7,6 @@ export interface ZoneMapperButtonProps extends ButtonProps {
 }
 /**
  * A convenience button to trigger the display of a ZoneMapper UI for ZoneGrid configuration.
- *
- * Requires a `ZoneGridModel.zoneMapperModel` config option, set to true for default implementation.
+ * Requires {@link ZoneGridConfig.zoneMapperModel} to be configured on the bound ZoneGridModel.
  */
 export declare const ZoneMapperButton: import("react").FC<ZoneMapperButtonProps>, zoneMapperButton: import("@xh/hoist/core").ElementFactory<ZoneMapperButtonProps>;

package/cmp/grid/GridModel.ts

@@ -283,7 +283,8 @@ export interface GridConfig {
      * Array of strings (or a function returning one) providing user-facing labels for each depth
      * level in a tree or grouped grid - e.g. `['Country', 'State', 'City']`. If set, the
      * expand/collapse options in the default context menu will be enhanced to allow users to
-     * expand/collapse to a specific level.
+     * expand/collapse to a specific level. See {@link GroupingChooserModel.valueDisplayNames}
+     * for a convenient getter that will satisfy this API when a GroupingChooser is in play.
      */
     levelLabels?: Thunkable<string[]>;
 

package/cmp/relativetimestamp/RelativeTimestamp.ts

@@ -4,6 +4,7 @@
  *
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
+import {getLayoutProps} from '@xh/hoist/utils/react';
 import {inRange, isNil} from 'lodash';
 import moment from 'moment';
 import {box, span} from '@xh/hoist/cmp/layout';
@@ -20,9 +21,9 @@ import {fmtCompactDate, fmtDateTime} from '@xh/hoist/format';
 import {action, computed, makeObservable, observable} from '@xh/hoist/mobx';
 import {Timer} from '@xh/hoist/utils/async';
 import {DAYS, HOURS, LocalDate, SECONDS} from '@xh/hoist/utils/datetime';
-import {logWarn, withDefault} from '@xh/hoist/utils/js';
+import {apiDeprecated, logWarn, withDefault} from '@xh/hoist/utils/js';
 
-interface RelativeTimestampProps extends HoistProps, BoxProps {
+interface RelativeTimestampProps extends HoistProps, BoxProps, RelativeTimestampOptions {
     /**
      * Property on context model containing timestamp.
      * Specify as an alternative to direct `timestamp` prop (and minimize parent re-renders).
@@ -32,7 +33,11 @@ interface RelativeTimestampProps extends HoistProps, BoxProps {
     /** Date or milliseconds representing the starting time / time to compare. See also `bind`. */
     timestamp?: Date | number;
 
-    /** Formatting options */
+    /**
+     * Formatting options.
+     *
+     * @deprecated - these options should be spread into this object directly.
+     */
     options?: RelativeTimestampOptions;
 }
 
@@ -91,13 +96,13 @@ export const [RelativeTimestamp, relativeTimestamp] = hoistCmp.withFactory<Relat
     displayName: 'RelativeTimestamp',
     className: 'xh-relative-timestamp',
 
-    render({className, bind, timestamp, options, ...rest}, ref) {
-        const impl = useLocalModel(RelativeTimestampLocalModel);
-
+    render({className, bind, timestamp, ...rest}, ref) {
+        const impl = useLocalModel(RelativeTimestampLocalModel),
+            layoutProps = getLayoutProps(rest);
         return box({
             className,
             ref,
-            ...rest,
+            ...layoutProps,
             item: span({
                 className: 'xh-title-tip',
                 item: impl.display,
@@ -128,7 +133,15 @@ class RelativeTimestampLocalModel extends HoistModel {
 
     @computed.struct
     get options(): RelativeTimestampOptions {
-        return this.componentProps.options;
+        const {componentProps} = this;
+
+        apiDeprecated('options', {
+            test: componentProps.options,
+            msg: 'Spread options directly in this object instead',
+            v: `77`
+        });
+
+        return componentProps.options ?? componentProps;
     }
 
     constructor() {

package/desktop/cmp/button/{ColAutosizeButton.ts → grid/ColAutosizeButton.ts}

@@ -4,15 +4,15 @@
  *
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
-import {GridModel, GridAutosizeOptions} from '@xh/hoist/cmp/grid';
+import {GridAutosizeOptions, GridModel} from '@xh/hoist/cmp/grid';
 import {hoistCmp, useContextModel} from '@xh/hoist/core';
 import '@xh/hoist/desktop/register';
 import {Icon} from '@xh/hoist/icon';
-import {errorIf, withDefault} from '@xh/hoist/utils/js';
-import {button, ButtonProps} from './Button';
+import {logError, withDefault} from '@xh/hoist/utils/js';
+import {button, ButtonProps} from '../Button';
 
 export interface ColAutosizeButtonProps extends ButtonProps {
-    /** GridModel of the grid for which this button should autosize columns. */
+    /** GridModel to which this button should bind. Will find nearest in context if not provided. */
     gridModel?: GridModel;
 
     /** Options for the grid autosize. */
@@ -24,15 +24,29 @@ export interface ColAutosizeButtonProps extends ButtonProps {
  */
 export const [ColAutosizeButton, colAutosizeButton] = hoistCmp.withFactory<ColAutosizeButtonProps>({
     displayName: 'ColAutosizeButton',
+    className: 'xh-col-autosize-button',
     model: false,
 
-    render({icon, title, onClick, gridModel, disabled, autosizeOptions = {}, ...rest}, ref) {
+    render(
+        {className, icon, title, onClick, gridModel, disabled, autosizeOptions = {}, ...rest},
+        ref
+    ) {
         gridModel = withDefault(gridModel, useContextModel(GridModel));
 
-        errorIf(
-            !gridModel,
-            "No GridModel available to ColAutosizeButton. Provide via a 'gridModel' prop, or context."
-        );
+        // Validate bound model available and suitable for use.
+        if (!gridModel) {
+            logError(
+                'No GridModel available - provide via a `gridModel` prop or context - button will be disabled.',
+                ColAutosizeButton
+            );
+            disabled = true;
+        } else if (!gridModel.autosizeEnabled) {
+            logError(
+                'Autosize not enabled on bound GridModel - button will be disabled.',
+                ColAutosizeButton
+            );
+            disabled = true;
+        }
 
         onClick =
             onClick ??
@@ -42,17 +56,13 @@ export const [ColAutosizeButton, colAutosizeButton] = hoistCmp.withFactory<ColAu
                     ...autosizeOptions
                 }));
 
-        errorIf(
-            !gridModel?.autosizeEnabled,
-            'AutosizeButton must be bound to GridModel with autosize enabled.  See autosizeOptions.mode'
-        );
-
         return button({
             ref,
             icon: withDefault(icon, Icon.arrowsLeftRight()),
             title: withDefault(title, 'Autosize Columns'),
+            disabled: withDefault(disabled, gridModel?.empty),
+            className,
             onClick,
-            disabled: withDefault(disabled, gridModel && gridModel.empty),
             ...rest
         });
     }

package/desktop/cmp/button/{ColChooserButton.ts → grid/ColChooserButton.ts}

@@ -13,10 +13,10 @@ import '@xh/hoist/desktop/register';
 import {Icon} from '@xh/hoist/icon';
 import {popover, Position} from '@xh/hoist/kit/blueprint';
 import {logError, stopPropagation, withDefault} from '@xh/hoist/utils/js';
-import {button, ButtonProps} from './Button';
+import {button, ButtonProps} from '../Button';
 
 export interface ColChooserButtonProps extends ButtonProps {
-    /** GridModel of the grid for which this button should show a chooser. */
+    /** GridModel to which this button should bind. Will find nearest in context if not provided. */
     gridModel?: GridModel;
 
     /** Position for chooser popover, as per Blueprint docs. */
@@ -28,28 +28,27 @@ export interface ColChooserButtonProps extends ButtonProps {
  * available Grid columns. For use by applications when a button is desired in addition to the
  * context menu item built into the Grid component directly.
  *
- * Requires the `GridModel.colChooserModel` config option. Set to true for default implementation.
+ * Requires {@link GridConfig.colChooserModel} to be configured on the bound GridModel.
  */
 export const [ColChooserButton, colChooserButton] = hoistCmp.withFactory<ColChooserButtonProps>({
     displayName: 'ColChooserButton',
+    className: 'xh-col-chooser-button',
     model: false,
 
-    render({icon, title, gridModel, popoverPosition, disabled, ...rest}, ref) {
+    render({className, icon, title, gridModel, popoverPosition, disabled, ...rest}, ref) {
         gridModel = withDefault(gridModel, useContextModel(GridModel));
-
         const colChooserModel = gridModel?.colChooserModel as ColChooserModel;
 
+        // Validate bound model available and suitable for use.
         if (!gridModel) {
             logError(
-                "No GridModel available.  Provide via a 'gridModel' prop, or context.",
+                'No GridModel available - provide via a `gridModel` prop or context - button will be disabled.',
                 ColChooserButton
             );
             disabled = true;
-        }
-
-        if (!colChooserModel) {
+        } else if (!colChooserModel) {
             logError(
-                'No ColChooserModel available on bound GridModel - enable via GridModel.colChooserModel config.',
+                'ColChooser not enabled on bound GridModel - button will be disabled.',
                 ColChooserButton
             );
             disabled = true;
@@ -62,6 +61,7 @@ export const [ColChooserButton, colChooserButton] = hoistCmp.withFactory<ColChoo
             item: button({
                 icon: withDefault(icon, Icon.gridPanel()),
                 title: withDefault(title, 'Choose grid columns...'),
+                className,
                 disabled,
                 ...rest
             }),

package/desktop/cmp/button/grid/ExpandToLevelButton.ts

@@ -0,0 +1,96 @@
+/*
+ * This file belongs to Hoist, an application development toolkit
+ * developed by Extremely Heavy Industries (www.xh.io | info@xh.io)
+ *
+ * Copyright © 2025 Extremely Heavy Industries Inc.
+ */
+import {GridModel} from '@xh/hoist/cmp/grid';
+import {div, vbox} from '@xh/hoist/cmp/layout';
+import {hoistCmp, MenuItemLike, useContextModel} from '@xh/hoist/core';
+import '@xh/hoist/desktop/register';
+import {Icon} from '@xh/hoist/icon';
+import {menu, popover, Position} from '@xh/hoist/kit/blueprint';
+import {parseMenuItems} from '@xh/hoist/utils/impl';
+import {executeIfFunction, logDebug, logError, withDefault} from '@xh/hoist/utils/js';
+import {ReactNode} from 'react';
+import {button, ButtonProps} from '../Button';
+
+export interface ExpandToLevelButtonProps extends Omit<ButtonProps, 'title'> {
+    /** GridModel to which this button should bind. Will find nearest in context if not provided. */
+    gridModel?: GridModel;
+
+    /** Position for menu, as per Blueprint docs. */
+    popoverPosition?: Position;
+
+    /** Title for the menu popover - defaults to "Expand To Level". */
+    title: ReactNode;
+}
+
+/**
+ * A menu button to expand a multi-level grouped or tree grid out to a desired level.
+ * Requires {@link GridConfig.levelLabels} to be configured on the bound GridModel.
+ */
+export const [ExpandToLevelButton, expandToLevelButton] =
+    hoistCmp.withFactory<ExpandToLevelButtonProps>({
+        displayName: 'ExpandToLevelButton',
+        className: 'xh-expand-to-level-button',
+        model: false,
+
+        render({gridModel, className, icon, title, popoverPosition, disabled, ...rest}) {
+            gridModel = withDefault(gridModel, useContextModel(GridModel));
+            icon = withDefault(icon, Icon.treeList());
+            title = withDefault(title, 'Expand To Level');
+
+            const disabledButton = () => button({icon, className, ...rest, disabled: true});
+
+            // Validate bound model available and suitable for use.
+            if (!gridModel) {
+                logError(
+                    'No GridModel available - provide via `gridModel` prop or context - button will be disabled.',
+                    ExpandToLevelButton
+                );
+                return disabledButton();
+            }
+
+            // Render a disabled button if requested or if we have a flat grid.
+            const {maxDepth, expandLevel} = gridModel;
+            if (disabled || !maxDepth) return disabledButton();
+
+            // Validate level labels - disable quietly if unspecified or w/log if mismatched to grid depth.
+            const levelLabels = executeIfFunction(gridModel.levelLabels);
+            if (!levelLabels) return disabledButton();
+            if (levelLabels.length < maxDepth + 1) {
+                logDebug(
+                    'Value produced by `GridModel.levelLabels` has insufficient length - button will be disabled.',
+                    ExpandToLevelButton
+                );
+                return disabledButton();
+            }
+
+            const menuItems: MenuItemLike[] = levelLabels.map((label, idx) => {
+                const isCurrLevel =
+                    expandLevel === idx ||
+                    (expandLevel > maxDepth && idx === levelLabels.length - 1);
+
+                return {
+                    icon: isCurrLevel ? Icon.check() : Icon.placeholder(),
+                    text: label,
+                    actionFn: () => gridModel.expandToLevel(idx)
+                };
+            });
+
+            return popover({
+                popoverClassName: 'xh-expand-to-level-button__popover xh-popup--framed',
+                position: withDefault(popoverPosition, 'auto'),
+                item: button({
+                    icon,
+                    className,
+                    ...rest
+                }),
+                content: vbox(
+                    div({className: 'xh-popup__title', item: title, omit: !title}),
+                    menu(parseMenuItems(menuItems))
+                )
+            });
+        }
+    });