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

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

@@ -0,0 +1,75 @@
+/*
+ * 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 {hoistCmp, useContextModel} from '@xh/hoist/core';
+import '@xh/hoist/desktop/register';
+import {Icon} from '@xh/hoist/icon';
+import {ExportOptions} from '@xh/hoist/svc';
+import {logError, withDefault} from '@xh/hoist/utils/js';
+import {button, 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 via props,
+ * otherwise will be looked up by this model from context.
+ *
+ * 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 {@link GridConfig.enableExport} option to be true on the bound GridModel.
+ */
+export const [ExportButton, exportButton] = hoistCmp.withFactory<ExportButtonProps>({
+    displayName: 'ExportButton',
+    className: 'xh-export-button',
+    model: false,
+
+    render(
+        {className, icon, title, onClick, gridModel, exportOptions = {}, disabled, ...rest},
+        ref
+    ) {
+        const contextGridModel = useContextModel(GridModel);
+
+        if (!onClick) {
+            gridModel = withDefault(gridModel, contextGridModel);
+
+            // 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.',
+                    ExportButton
+                );
+                disabled = true;
+            } else if (!gridModel.enableExport) {
+                logError(
+                    'Export not enabled on bound GridModel - button will be disabled',
+                    ExportButton
+                );
+                disabled = true;
+            } else {
+                onClick = () => gridModel.exportAsync(exportOptions).catchDefault();
+            }
+        }
+
+        return button({
+            ref,
+            icon: withDefault(icon, Icon.download()),
+            title: withDefault(title, 'Export'),
+            disabled: withDefault(disabled, gridModel && gridModel.empty),
+            className,
+            onClick,
+            ...rest
+        });
+    }
+});

package/desktop/cmp/button/index.ts

@@ -1,17 +1,18 @@
 // Export button first as others (e.g. AppMenuButton) depend on its static propTypes.
-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/desktop/cmp/button/{ModalToggleButton.ts → panel/ModalToggleButton.ts}

@@ -9,7 +9,7 @@ import {button, ButtonProps} from '@xh/hoist/desktop/cmp/button/Button';
 import {PanelModel} from '@xh/hoist/desktop/cmp/panel';
 import '@xh/hoist/desktop/register';
 import {Icon} from '@xh/hoist/icon';
-import {errorIf, withDefault} from '@xh/hoist/utils/js';
+import {logError, withDefault} from '@xh/hoist/utils/js';
 
 export interface ModalToggleButtonProps extends ButtonProps {
     panelModel?: PanelModel;
@@ -20,21 +20,27 @@ export interface ModalToggleButtonProps extends ButtonProps {
  */
 export const [ModalToggleButton, modalToggleButton] = hoistCmp.withFactory<ModalToggleButtonProps>({
     displayName: 'ModalToggleButton',
+    className: 'xh-modal-toggle-button',
     model: false,
 
-    render({panelModel, ...rest}, ref) {
+    render({className, panelModel, disabled, ...rest}, ref) {
         panelModel = withDefault(panelModel, useContextModel(PanelModel));
 
-        errorIf(
-            !panelModel,
-            "No PanelModel available to ModalToggleButton. Provide via 'panelModel' prop, or context."
-        );
+        if (!panelModel) {
+            logError(
+                'No PanelModel available - provide via `panelModel` prop or context - button will be disabled.',
+                ModalToggleButton
+            );
+            disabled = true;
+        }
 
         return button({
             ref,
             icon: panelModel.isModal ? Icon.close() : Icon.openExternal(),
             onClick: () => panelModel.toggleIsModal(),
             minimal: true,
+            className,
+            disabled,
             ...rest
         });
     }

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

@@ -13,10 +13,10 @@ import {zoneMapper} from '@xh/hoist/desktop/cmp/zoneGrid/impl/ZoneMapper';
 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 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. */
@@ -25,28 +25,27 @@ 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 const [ZoneMapperButton, zoneMapperButton] = hoistCmp.withFactory<ZoneMapperButtonProps>({
     displayName: 'ZoneMapperButton',
+    className: 'xh-zone-mapper-button',
     model: false,
-    render({icon, title, zoneGridModel, popoverPosition, disabled, ...rest}, ref) {
-        zoneGridModel = withDefault(zoneGridModel, useContextModel(ZoneGridModel));
 
+    render({className, icon, title, zoneGridModel, popoverPosition, disabled, ...rest}, ref) {
+        zoneGridModel = withDefault(zoneGridModel, useContextModel(ZoneGridModel));
         const mapperModel = zoneGridModel?.mapperModel as ZoneMapperModel;
 
+        // Validate bound model available and suitable for use.
         if (!zoneGridModel) {
             logError(
-                "No ZoneGridModel available. Provide via a 'zoneGridModel' prop, or context.",
+                'No ZoneGridModel available - provide via `zoneGridModel` prop or context - button will be disabled',
                 ZoneMapperButton
             );
             disabled = true;
-        }
-
-        if (!mapperModel) {
+        } else if (!mapperModel) {
             logError(
-                'No ZoneMapperModel available on bound ZoneGridModel - enable via ZoneGridModel.zoneMapperModel config.',
+                'ZoneMapper not enabled on bound ZoneGridModel - button will be disabled.',
                 ZoneMapperButton
             );
             disabled = true;
@@ -60,6 +59,7 @@ export const [ZoneMapperButton, zoneMapperButton] = hoistCmp.withFactory<ZoneMap
             item: button({
                 icon: withDefault(icon, Icon.gridLarge()),
                 title: withDefault(title, 'Customize fields...'),
+                className,
                 disabled,
                 ...rest
             }),

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

@@ -13,10 +13,10 @@ import '@xh/hoist/mobile/register';
 import {logError, withDefault} from '@xh/hoist/utils/js';
 
 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'>;
 }
 
@@ -25,17 +25,27 @@ export interface ColAutosizeButtonProps extends ButtonProps {
  */
 export const [ColAutosizeButton, colAutosizeButton] = hoistCmp.withFactory<ColAutosizeButtonProps>({
     displayName: 'ColAutosizeButton',
+    className: 'xh-col-autosize-button',
     model: false,
 
-    render({gridModel, icon = Icon.arrowsLeftRight(), onClick, autosizeOptions = {}, ...props}) {
+    render({className, gridModel, icon, onClick, disabled, autosizeOptions = {}, ...props}) {
         gridModel = withDefault(gridModel, useContextModel(GridModel));
 
-        if (!gridModel?.autosizeEnabled) {
-            logError(
-                "No GridModel available with autosize enabled. Provide via a 'gridModel' prop, or context.",
-                ColAutosizeButton
-            );
-            return button({icon, disabled: true, ...props});
+        // Validate bound model available and suitable for use.
+        if (!onClick) {
+            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 =
@@ -46,6 +56,12 @@ export const [ColAutosizeButton, colAutosizeButton] = hoistCmp.withFactory<ColAu
                     ...autosizeOptions
                 }));
 
-        return button({icon, onClick, ...props});
+        return button({
+            icon: withDefault(icon, Icon.arrowsLeftRight()),
+            disabled: withDefault(disabled, gridModel?.empty),
+            className,
+            onClick,
+            ...props
+        });
     }
 });

package/mobile/cmp/button/grid/ColChooserButton.ts

@@ -0,0 +1,58 @@
+/*
+ * 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 {hoistCmp, useContextModel} from '@xh/hoist/core';
+import {Icon} from '@xh/hoist/icon';
+import {button, ButtonProps} from '@xh/hoist/mobile/cmp/button';
+import '@xh/hoist/mobile/register';
+import {logError, withDefault} from '@xh/hoist/utils/js';
+
+export interface ColChooserButtonProps extends ButtonProps {
+    /** 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.
+ *
+ * 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({className, gridModel, icon, onClick, disabled, ...props}) {
+        gridModel = withDefault(gridModel, useContextModel(GridModel));
+
+        if (!onClick) {
+            // 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.',
+                    ColChooserButton
+                );
+                disabled = true;
+            } else if (!gridModel.colChooserModel) {
+                logError(
+                    'ColChooser not enabled on bound GridModel - button will be disabled.',
+                    ColChooserButton
+                );
+                disabled = true;
+            }
+        }
+
+        onClick = onClick ?? (() => gridModel.showColChooser());
+        return button({
+            icon: withDefault(icon, Icon.gridPanel()),
+            disabled,
+            onClick,
+            ...props
+        });
+    }
+});

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

@@ -13,23 +13,29 @@ import {logError, withDefault} from '@xh/hoist/utils/js';
 import {isEmpty} from 'lodash';
 
 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 const [ExpandCollapseButton, expandCollapseButton] =
     hoistCmp.withFactory<ExpandCollapseButtonProps>({
         displayName: 'ExpandCollapseButton',
+        className: 'xh-expand-collapse-button',
         model: false,
-        render({gridModel, onClick, ...props}) {
+
+        render({className, gridModel, onClick, ...props}) {
             gridModel = withDefault(gridModel, useContextModel(GridModel));
 
-            if (!gridModel) {
+            // Validate bound model available and suitable for use.
+            if (!onClick && !gridModel) {
                 logError(
-                    "No GridModel available. Provide via a 'gridModel' prop, or context.",
+                    'No GridModel available - provide via `gridModel` prop or context - button will be disabled.',
                     ExpandCollapseButton
                 );
                 return button({icon: Icon.expand(), disabled: true, ...props});
@@ -45,6 +51,6 @@ export const [ExpandCollapseButton, expandCollapseButton] =
                 onClick ??
                 (() => (shouldCollapse ? gridModel.collapseAll() : gridModel.expandAll()));
 
-            return button({disabled, icon, onClick, ...props});
+            return button({className, disabled, icon, onClick, ...props});
         }
     });

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

@@ -0,0 +1,91 @@
+/*
+ * 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 {hoistCmp, MenuItemLike, useContextModel} from '@xh/hoist/core';
+import {Icon} from '@xh/hoist/icon';
+import '@xh/hoist/mobile/register';
+import {executeIfFunction, logDebug, logError, withDefault} from '@xh/hoist/utils/js';
+import {menuButton, 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 const [ExpandToLevelButton, expandToLevelButton] =
+    hoistCmp.withFactory<ExpandToLevelButtonProps>({
+        displayName: 'ExpandToLevelButton',
+        className: 'xh-expand-to-level-button',
+        model: false,
+
+        render({gridModel, className, icon, ...rest}) {
+            gridModel = withDefault(gridModel, useContextModel(GridModel));
+            icon = withDefault(icon, Icon.treeList());
+
+            const disabledButton = () =>
+                menuButton({
+                    icon,
+                    className,
+                    ...rest,
+                    disabled: true,
+                    menuItems: []
+                });
+
+            if (!gridModel) {
+                logError(
+                    "No GridModel available. Provide via a 'gridModel' prop, or context.",
+                    ExpandToLevelButton
+                );
+                return disabledButton();
+            }
+
+            // Disable for flat grids. Still show for grids with a single grouping level, although
+            // in this case we're effectively a less efficient way to expand/collapse all.
+            const {maxDepth, expandLevel} = gridModel;
+            if (!maxDepth) return disabledButton();
+
+            // Validate level labels - disable if unspecified or 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. No menu items shown.',
+                    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 menuButton({
+                title: 'Expand To',
+                icon,
+                className,
+                menuItems,
+                ...rest
+            });
+        }
+    });

package/mobile/cmp/button/index.ts

@@ -6,13 +6,14 @@
  */
 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/mobile/cmp/button/zoneGrid/ZoneMapperButton.ts

@@ -0,0 +1,58 @@
+/*
+ * 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 {hoistCmp, useContextModel} from '@xh/hoist/core';
+import {Icon} from '@xh/hoist/icon';
+import {button, ButtonProps} from '@xh/hoist/mobile/cmp/button';
+import {logError, withDefault} from '@xh/hoist/utils/js';
+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. */
+    zoneGridModel?: ZoneGridModel;
+}
+
+/**
+ * A convenience button to trigger the display of a ZoneMapper UI for ZoneGrid configuration.
+ * Requires {@link ZoneGridConfig.zoneMapperModel} to be configured on the bound ZoneGridModel.
+ */
+export const [ZoneMapperButton, zoneMapperButton] = hoistCmp.withFactory<ZoneMapperButtonProps>({
+    displayName: 'ZoneMapperButton',
+    className: 'xh-zone-mapper-button',
+    model: false,
+
+    render({className, icon, zoneGridModel, onClick, disabled, ...rest}) {
+        zoneGridModel = withDefault(zoneGridModel, useContextModel(ZoneGridModel));
+
+        // Validate bound model available and suitable for use.
+        if (!onClick) {
+            if (!zoneGridModel) {
+                logError(
+                    'No ZoneGridModel available - provide via `zoneGridModel` prop or context - button will be disabled',
+                    ZoneMapperButton
+                );
+                disabled = true;
+            } else if (!zoneGridModel.mapperModel) {
+                logError(
+                    'ZoneMapper not enabled on bound ZoneGridModel - button will be disabled.',
+                    ZoneMapperButton
+                );
+                disabled = true;
+            }
+        }
+
+        onClick = onClick ?? (() => zoneGridModel.showMapper());
+
+        return button({
+            icon: withDefault(icon, Icon.gridLarge()),
+            className,
+            disabled,
+            onClick,
+            ...rest
+        });
+    }
+});

package/package.json

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