@xh/hoist 80.0.0-SNAPSHOT.1768003263151 → 80.0.0-SNAPSHOT.1768251400948

package/desktop/cmp/dash/canvas/DashCanvasModel.ts

@@ -4,6 +4,7 @@
  *
  * Copyright © 2026 Extremely Heavy Industries Inc.
  */
+import {wait} from '@xh/hoist/promise';
 import type {LayoutItem} from 'react-grid-layout';
 import {Persistable, PersistableState, PersistenceProvider, XH} from '@xh/hoist/core';
 import {required} from '@xh/hoist/data';
@@ -17,6 +18,7 @@ import {createObservableRef} from '@xh/hoist/utils/react';
 import {
     defaultsDeep,
     find,
+    omit,
     uniqBy,
     times,
     without,
@@ -41,11 +43,12 @@ export interface DashCanvasConfig extends DashConfig<DashCanvasViewSpec, DashCan
     rowHeight?: number;
 
     /**
-     * Whether views should "compact" vertically or horizontally
+     * Whether views should "compact" vertically, horizontally or wrap
      * to condense space. Default `true` defaults to vertical compaction.
+     * Use `wrap` with caution.  It only works well if all items are 1 row high.
      * See react-grid-layout docs for more information.
-     * */
-    compact?: boolean | 'vertical' | 'horizontal';
+     */
+    compact?: boolean | 'vertical' | 'horizontal' | 'wrap';
 
     /** Between items [x,y] in pixels. Default `[10, 10]`. */
     margin?: [number, number];
@@ -60,6 +63,35 @@ export interface DashCanvasConfig extends DashConfig<DashCanvasViewSpec, DashCan
      * Whether a grid background should be shown. Default false.
      */
     showGridBackground?: boolean;
+
+    /**
+     * Whether the canvas should accept drag-and-drop of views from outside
+     * the canvas. Default false.
+     */
+    allowsDrop?: boolean;
+
+    /**
+     * Optional callback to invoke after a view is successfully dropped onto the canvas.
+     */
+    onDropDone?: (viewModel: DashCanvasViewModel) => void;
+
+    /**
+     * Optional callback to invoke when an item is dragged over the canvas. This may be used to
+     * customize how the size of the dropping placeholder is calculated. The callback should
+     * return an object with optional properties indicating the desired width, height (in grid units),
+     * and offset (in pixels) of the dropping placeholder.  The method's signature is the same as
+     * the `onDropDragOver` prop of ReactGridLayout.
+     * Returning `false` will prevent the dropping placeholder from being shown, and prevents a drop.
+     * Returning `void` will use the default behavior, which is to size the placeholder as per the
+     * `dropConfig.defaultItem` specification.
+     */
+    onDropDragOver?: (e: DragEvent) => OnDropDragOverResult;
+
+    /**
+     * Whether an overlay with an Add View button should be rendered
+     * when the canvas is empty. Default true.
+     */
+    showAddViewButtonWhenEmpty?: boolean;
 }
 
 export interface DashCanvasItemState {
@@ -76,6 +108,16 @@ export interface DashCanvasItemLayout {
     h: number;
 }
 
+export type OnDropDragOverResult =
+    | {
+          w?: number;
+          h?: number;
+          dragOffsetX?: number;
+          dragOffsetY?: number;
+      }
+    | false
+    | void;
+
 /**
  * Model for {@link DashCanvas}, managing all configurable options for the component and publishing
  * the observable state of its current widgets and their layout.
@@ -89,16 +131,21 @@ export class DashCanvasModel
     //------------------------------
     @bindable columns: number;
     @bindable rowHeight: number;
-    @bindable compact: 'vertical' | 'horizontal';
+    @bindable compact: 'vertical' | 'horizontal' | 'wrap';
     @bindable.ref margin: [number, number]; // [x, y]
     @bindable.ref containerPadding: [number, number]; // [x, y]
     @bindable showGridBackground: boolean;
     @bindable rglHeight: number;
+    @bindable showAddViewButtonWhenEmpty: boolean;
 
     //-----------------------------
     // Public properties
     //-----------------------------
+    DROPPING_ELEM_ID = '__dropping-elem__';
     maxRows: number;
+    allowsDrop: boolean;
+    onDropDone: (viewModel: DashCanvasViewModel) => void;
+    draggedInView: DashCanvasItemState;
 
     /** Current number of rows in canvas */
     get rows(): number {
@@ -118,21 +165,27 @@ export class DashCanvasModel
     private isLoadingState: boolean;
 
     get rglLayout() {
-        return this.layout.map(it => {
-            const dashCanvasView = this.getView(it.i),
-                {autoHeight, viewSpec} = dashCanvasView;
-
-            return {
-                ...it,
-                resizeHandles: autoHeight
-                    ? ['w', 'e']
-                    : ['s', 'w', 'e', 'n', 'sw', 'nw', 'se', 'ne'],
-                maxH: viewSpec.maxHeight,
-                minH: viewSpec.minHeight,
-                maxW: viewSpec.maxWidth,
-                minW: viewSpec.minWidth
-            };
-        });
+        return this.layout
+            .map(it => {
+                const dashCanvasView = this.getView(it.i);
+
+                // `dashCanvasView` will not be found if `it` is a dropping element.
+                if (!dashCanvasView) return null;
+
+                const {autoHeight, viewSpec} = dashCanvasView;
+
+                return {
+                    ...it,
+                    resizeHandles: autoHeight
+                        ? ['w', 'e']
+                        : ['s', 'w', 'e', 'n', 'sw', 'nw', 'se', 'ne'],
+                    maxH: viewSpec.maxHeight,
+                    minH: viewSpec.minHeight,
+                    maxW: viewSpec.maxWidth,
+                    minW: viewSpec.minWidth
+                };
+            })
+            .filter(Boolean);
     }
 
     constructor({
@@ -152,7 +205,11 @@ export class DashCanvasModel
         maxRows = Infinity,
         containerPadding = margin,
         extraMenuItems,
-        showGridBackground = false
+        showGridBackground = false,
+        showAddViewButtonWhenEmpty = true,
+        allowsDrop = false,
+        onDropDone,
+        onDropDragOver
     }: DashCanvasConfig) {
         super();
         makeObservable(this);
@@ -200,6 +257,10 @@ export class DashCanvasModel
         this.addViewButtonText = addViewButtonText;
         this.extraMenuItems = extraMenuItems;
         this.showGridBackground = showGridBackground;
+        this.showAddViewButtonWhenEmpty = showAddViewButtonWhenEmpty;
+        this.allowsDrop = allowsDrop;
+        this.onDropDone = onDropDone;
+        if (onDropDragOver) this.onDropDragOver = onDropDragOver;
 
         this.loadState(initialState);
         this.state = this.buildState();
@@ -337,6 +398,59 @@ export class DashCanvasModel
         this.getView(id)?.ensureVisible();
     }
 
+    onDrop(rglLayout: LayoutItem[], layoutItem: LayoutItem, evt: Event) {
+        throwIf(
+            !this.draggedInView,
+            `No draggedInView set on DashCanvasModel prior to onDrop operation.
+            Typically a developer would set this in response to dragstart events from
+             a DashViewTray or similar component.`
+        );
+
+        const droppingItem: any = rglLayout.find(it => it.i === this.DROPPING_ELEM_ID);
+        if (!droppingItem) {
+            // if `onDropDragOver` returned false, we won't have a dropping item
+            // and we cancel the drop
+            this.draggedInView = null;
+            return;
+        }
+
+        const {viewSpecId, title, state} = this.draggedInView,
+            layout = omit(layoutItem, 'i'),
+            newViewModel: DashCanvasViewModel = this.addViewInternal(viewSpecId, {
+                title,
+                state,
+                layout
+            });
+
+        // Change ID of dropping item to the new view's id
+        // so that the new view goes where the dropping item is.
+        droppingItem.i = newViewModel.id;
+
+        // must wait a tick for RGL to settle
+        wait().then(() => {
+            this.draggedInView = null;
+            this.onRglLayoutChange(rglLayout);
+            this.onDropDone?.(newViewModel);
+        });
+    }
+
+    setDraggedInView(view?: DashCanvasItemState) {
+        this.draggedInView = view;
+    }
+
+    onDropDragOver(evt: DragEvent): OnDropDragOverResult {
+        if (!this.draggedInView) return false;
+
+        return {
+            w: this.draggedInView.layout.w,
+            h: this.draggedInView.layout.h
+        };
+    }
+
+    getViewsBySpecId(id) {
+        return this.viewModels.filter(it => it.viewSpec.id === id);
+    }
+
     //------------------------
     // Persistable Interface
     //------------------------
@@ -413,6 +527,12 @@ export class DashCanvasModel
 
     onRglLayoutChange(rglLayout: LayoutItem[]) {
         rglLayout = rglLayout.map(it => pick(it, ['i', 'x', 'y', 'w', 'h']));
+
+        // Early out if RGL is changing layout as user is dragging droppable
+        // item around the canvas.  This will be called again once dragging
+        // has stopped and user has dropped the item onto the canvas.
+        if (rglLayout.some(it => it.i === this.DROPPING_ELEM_ID)) return;
+
         this.setLayout(rglLayout);
     }
 
@@ -496,10 +616,6 @@ export class DashCanvasModel
         return some(this.viewSpecs, {id});
     }
 
-    private getViewsBySpecId(id) {
-        return this.viewModels.filter(it => it.viewSpec.id === id);
-    }
-
     private getNextAvailablePosition({
         width,
         height,

package/desktop/cmp/dash/canvas/widgetwell/DashCanvasWidgetWell.scss

@@ -0,0 +1,34 @@
+.xh-dash-canvas-widget-well {
+  padding: 0 var(--xh-pad-half-px);
+
+  .xh-collapsible-set {
+    padding: 0 var(--xh-pad-half-px) var(--xh-pad-half-px) var(--xh-pad-half-px);
+    margin: var(--xh-pad-half-px);
+  }
+
+  .xh-dash-canvas-draggable-widget {
+    border: var(--xh-border-dotted);
+    background-color: var(--xh-bg-alt);
+    padding: var(--xh-pad-half-px);
+    margin: var(--xh-pad-half-px);
+    text-wrap-mode: nowrap;
+    cursor: grab;
+
+    &.is-dragging {
+      cursor: grabbing;
+      // lighten background color of left behind placeholder
+      // when dragging
+      opacity: 0.25;
+    }
+
+    &:active {
+      cursor: grabbing;
+    }
+  }
+
+  &--row {
+    .xh-dash-canvas-draggable-widget {
+      align-self: flex-start;
+    }
+  }
+}

package/desktop/cmp/dash/canvas/widgetwell/DashCanvasWidgetWell.ts

@@ -0,0 +1,135 @@
+/*
+ * 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 {uniqBy} from 'lodash';
+import classNames from 'classnames';
+import type {ReactElement} from 'react';
+import {div, frame} from '@xh/hoist/cmp/layout';
+import {creates, hoistCmp, HoistProps, TestSupportProps, uses} from '@xh/hoist/core';
+import {DashCanvasModel, DashCanvasViewSpec} from '@xh/hoist/desktop/cmp/dash';
+import {DashCanvasWidgetWellModel} from '@xh/hoist/desktop/cmp/dash/canvas/widgetwell/DashCanvasWidgetWellModel';
+import {collapsibleSet} from '@xh/hoist/cmp/layout/CollapsibleSet';
+
+import './DashCanvasWidgetWell.scss';
+
+export interface DashCanvasWidgetWellProps extends HoistProps, TestSupportProps {
+    /** DashCanvasModel for which this widget well should allow the user to add views from. */
+    dashCanvasModel?: DashCanvasModel;
+    /** Defaults to `column` */
+    flexDirection?: 'row' | 'column';
+}
+
+/**
+ * Widget Well from which to add items to a DashCanvas by drag-and-drop.
+ *
+ * Available view specs are listed in their defined order,
+ * grouped by their 'groupName' property if present.
+ *
+ * Typically, an app developer would place this inside a collapsible panel to the side of
+ * a DashCanvas.
+ */
+export const [DashCanvasWidgetWell, dashCanvasWidgetWell] =
+    hoistCmp.withFactory<DashCanvasWidgetWellProps>({
+        displayName: 'DashCanvasWidgetWell',
+        model: creates(DashCanvasWidgetWellModel),
+        className: 'xh-dash-canvas-widget-well',
+        render({dashCanvasModel, flexDirection, className, testId}) {
+            if (!dashCanvasModel) return;
+
+            const classes = [];
+            if (flexDirection === 'row') classes.push('xh-dash-canvas-widget-well--row');
+
+            return frame({
+                className: classNames(className, classes),
+                overflowY: 'auto',
+                flexDirection: flexDirection || 'column',
+                flexWrap: flexDirection === 'row' ? 'wrap' : 'nowrap',
+                items: createDraggableItems(dashCanvasModel, flexDirection),
+                testId
+            });
+        }
+    });
+
+//---------------------------
+// Implementation
+//---------------------------
+const draggableWidget = hoistCmp.factory<DashCanvasWidgetWellModel>({
+    displayName: 'DraggableWidget',
+    model: uses(DashCanvasWidgetWellModel),
+    render({model, viewSpec}) {
+        const {id, icon, title} = viewSpec as DashCanvasViewSpec;
+        return div({
+            id: `draggableFor-${id}`,
+            className: 'xh-dash-canvas-draggable-widget',
+            draggable: true,
+            unselectable: 'on',
+            onDragStart: e => model.onDragStart(e),
+            onDragEnd: e => model.onDragEnd(e),
+            items: [icon, ' ', title]
+        });
+    }
+});
+
+/**
+ * Used to create draggable items (for adding views)
+ * @internal
+ */
+function createDraggableItems(dashCanvasModel: DashCanvasModel, flexDirection): any[] {
+    if (!dashCanvasModel.ref.current) return [];
+
+    const groupedItems = {},
+        ungroupedItems = [];
+
+    const addToGroup = (item, icon, groupName) => {
+        const group = groupedItems[groupName];
+        if (group) {
+            group.push({item, icon});
+        } else {
+            groupedItems[groupName] = [{item, icon}];
+        }
+    };
+
+    dashCanvasModel.viewSpecs
+        .filter(viewSpec => {
+            return (
+                viewSpec.allowAdd &&
+                (!viewSpec.unique || !dashCanvasModel.getViewsBySpecId(viewSpec.id).length)
+            );
+        })
+        .forEach(viewSpec => {
+            const {groupName} = viewSpec,
+                item = draggableWidget({viewSpec});
+
+            if (groupName) {
+                addToGroup(item, viewSpec.icon, groupName);
+            } else {
+                ungroupedItems.push(item);
+            }
+        });
+
+    return [
+        ...Object.keys(groupedItems).map(group => {
+            const label = group,
+                items = groupedItems[group],
+                sameIcons =
+                    uniqBy<{item: ReactElement; icon: ReactElement}>(
+                        items,
+                        it => it.icon.props.iconName
+                    ).length === 1,
+                icon = sameIcons ? items[0].icon : null;
+
+            return collapsibleSet({
+                icon,
+                collapsed: false,
+                label,
+                flexDirection,
+                items: items.map(it => it.item)
+            });
+        }),
+        ...ungroupedItems
+    ];
+}

package/desktop/cmp/dash/canvas/widgetwell/DashCanvasWidgetWellModel.ts

@@ -0,0 +1,65 @@
+/*
+ * 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 {DragEvent} from 'react';
+import {DashCanvasModel} from '@xh/hoist/desktop/cmp/dash';
+import {HoistModel, managed} from '@xh/hoist/core';
+import '@xh/hoist/desktop/register';
+import {makeObservable, observable} from '@xh/hoist/mobx';
+import {runInAction} from 'mobx';
+
+export class DashCanvasWidgetWellModel extends HoistModel {
+    @managed
+    @observable.ref
+    dashCanvasModel: DashCanvasModel;
+
+    constructor() {
+        super();
+        makeObservable(this);
+    }
+
+    override onLinked() {
+        this.addReaction({
+            track: () => this.componentProps,
+            run: () =>
+                runInAction(() => (this.dashCanvasModel = this.componentProps.dashCanvasModel)),
+            fireImmediately: true
+        });
+    }
+
+    onDragStart(evt: DragEvent<HTMLDivElement>) {
+        const target = evt.target as HTMLElement;
+        if (!target) return;
+
+        this.dashCanvasModel.showAddViewButtonWhenEmpty = false;
+        evt.dataTransfer.effectAllowed = 'move';
+        target.classList.add('is-dragging');
+
+        const viewSpecId: string = target.getAttribute('id').split('draggableFor-')[1],
+            viewSpec = this.dashCanvasModel.viewSpecs.find(it => it.id === viewSpecId),
+            {width, height} = viewSpec,
+            widget = {
+                viewSpecId,
+                layout: {
+                    x: 0,
+                    y: 0,
+                    w: width,
+                    h: height
+                }
+            };
+
+        this.dashCanvasModel.setDraggedInView(widget);
+    }
+
+    onDragEnd(evt: DragEvent<HTMLDivElement>) {
+        this.dashCanvasModel.showAddViewButtonWhenEmpty = true;
+
+        const target = evt.target as HTMLElement;
+        if (!target) return;
+
+        target.classList.remove('is-dragging');
+    }
+}

package/dynamics/desktop.ts

@@ -15,6 +15,7 @@
  *
  * See the platform specific AppContainer where these implementations are actually provided.
  */
+export let collapsibleSetButton = null;
 export let ColChooserModel = null;
 export let ColumnHeaderFilterModel = null;
 export let ModalSupportModel = null;
@@ -37,6 +38,7 @@ export let DynamicTabSwitcherModel = null;
  * Not for Application use.
  */
 export function installDesktopImpls(impls) {
+    collapsibleSetButton = impls.collapsibleSetButton;
     ColChooserModel = impls.ColChooserModel;
     ColumnHeaderFilterModel = impls.ColumnHeaderFilterModel;
     ModalSupportModel = impls.ModalSupportModel;

package/dynamics/mobile.ts

@@ -15,6 +15,7 @@
  *
  * See the platform specific AppContainer where these implementations are actually provided.
  */
+export let collapsibleSetButton = null;
 export let ColChooserModel = null;
 export let colChooser = null;
 export let zoneMapper = null;
@@ -30,6 +31,7 @@ export let maskImpl = null;
  * Not for Application use.
  */
 export function installMobileImpls(impls) {
+    collapsibleSetButton = impls.collapsibleSetButton;
     ColChooserModel = impls.ColChooserModel;
     colChooser = impls.colChooser;
     zoneMapper = impls.zoneMapper;

package/mobile/appcontainer/AppContainer.ts

@@ -18,6 +18,7 @@ import {pinPadImpl} from '@xh/hoist/mobile/cmp/pinpad/impl/PinPad';
 import {storeFilterFieldImpl} from '@xh/hoist/mobile/cmp/store/impl/StoreFilterField';
 import {tabContainerImpl} from '@xh/hoist/mobile/cmp/tab/impl/TabContainer';
 import {zoneMapper} from '@xh/hoist/mobile/cmp/zoneGrid/impl/ZoneMapper';
+import {collapsibleSetButton} from '@xh/hoist/mobile/cmp/button/CollapsibleSetButton';
 import {elementFromContent, useOnMount} from '@xh/hoist/utils/react';
 import {isEmpty} from 'lodash';
 import {aboutDialog} from './AboutDialog';
@@ -34,6 +35,7 @@ import {toastSource} from './ToastSource';
 import {versionBar} from './VersionBar';
 
 installMobileImpls({
+    collapsibleSetButton,
     tabContainerImpl,
     storeFilterFieldImpl,
     pinPadImpl,

package/mobile/cmp/button/CollapsibleSetButton.ts

@@ -0,0 +1,57 @@
+/*
+ * This file belongs to Hoist, an application development toolkit
+ * developed by Extremely Heavy Industries (www.xh.io | info@xh.io)
+ *
+ * Copyright © 2026 Extremely Heavy Industries Inc.
+ */
+
+import {type ReactElement, type ReactNode, type JSX, useState} from 'react';
+import {tooltip as bpTooltip} from '@xh/hoist/kit/blueprint';
+import {fragment} from '@xh/hoist/cmp/layout';
+import {hoistCmp} from '@xh/hoist/core';
+import type {Intent, HoistProps} from '@xh/hoist/core';
+import {button} from '@xh/hoist/mobile/cmp/button';
+import {legend} from '@xh/hoist/cmp/layout';
+import {Icon} from '@xh/hoist/icon/Icon';
+
+export interface CollapsibleSetButtonProps extends HoistProps {
+    icon?: ReactElement;
+    text: ReactNode;
+    tooltip?: JSX.Element | string;
+    clickHandler?: (boolean) => void;
+    intent?: Intent;
+    collapsed?: boolean;
+    disabled?: boolean;
+}
+
+export const [CollapsibleSetButton, collapsibleSetButton] =
+    hoistCmp.withFactory<CollapsibleSetButtonProps>({
+        displayName: 'CollapsibleSetButton',
+        model: false,
+        render({icon, text, tooltip, intent, clickHandler, collapsed, disabled}) {
+            const [isCollapsed, setIsCollapsed] = useState<boolean>(collapsed === true),
+                btn = button({
+                    text: fragment(text, isCollapsed ? Icon.angleDown() : Icon.angleUp()),
+                    icon,
+                    outlined: isCollapsed && !intent,
+                    minimal: !intent || (intent && !isCollapsed),
+                    intent,
+                    disabled,
+                    onClick: () => {
+                        const val = !isCollapsed;
+                        setIsCollapsed(val);
+                        clickHandler?.(val);
+                    }
+                });
+
+            return legend(
+                tooltip
+                    ? bpTooltip({
+                          item: btn,
+                          content: tooltip,
+                          intent
+                      })
+                    : btn
+            );
+        }
+    });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xh/hoist",
-  "version": "80.0.0-SNAPSHOT.1768003263151",
+  "version": "80.0.0-SNAPSHOT.1768251400948",
   "description": "Hoist add-on for building and deploying React Applications.",
   "repository": "github:xh/hoist-react",
   "homepage": "https://xh.io",
@@ -62,11 +62,11 @@
     "moment": "~2.30.1",
     "numbro": "~2.5.0",
     "onsenui": "~2.12.8",
-    "qs": "~6.14.0",
+    "qs": "~6.14.1",
     "react-beautiful-dnd": "~13.1.0",
     "react-dates": "~21.8.0",
     "react-dropzone": "~10.2.2",
-    "react-grid-layout": "2.1.1",
+    "react-grid-layout": "2.2.2",
     "react-markdown": "~10.1.0",
     "react-onsenui": "~1.13.2",
     "react-popper": "~2.3.0",